Automation API
Start an email automation for a specific subscriber from your own application, shop or CRM, and pass custom data into the emails it sends.
Overview
This endpoint starts an email automation for one subscriber, on demand. Use it when something happens in your own system that should kick off a sequence — an abandoned cart, a new purchase, a change in account activity.
Authentication
All API requests require authentication using your API key.
Y-API-Key header in all requests. Create and find your API key at Settings → Connections → MCP & API keys.Endpoint Details
POST https://yaplet.com/api/newsletter/workflow/start
Starts an automation for a specific subscriber. The subscriber must be a verified newsletter contact in your organization, and the automation must be switched on and use the Your app calls our API trigger.
workflow_id body field and the response messages all keep the word workflow: the feature was renamed on screen from "Workflows" to "Email automations", and these names stayed so existing integrations carry on working. Do not change them in your code.Request Structure
Headers
{
"Content-Type": "application/json",
"Y-API-Key": "YOUR_API_KEY"
}
Request Body
{
"email": "[email protected]",
"workflow_id": "your-workflow-id",
"key1": "value1",
"key2": "value2"
}
email and workflow_id, not nested inside a separate object.Response Examples
Successful Start
Status: 200 OK
{
"success": true
}
Already Queued
Status: 200 OK
{
"success": true,
"message": "Workflow run already queued"
}
If the subscriber already has a pending run for this automation, the API returns success without creating a duplicate.
Code Examples
const response = await fetch("https://yaplet.com/api/newsletter/workflow/start", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Y-API-Key": "YOUR_API_KEY"
},
body: JSON.stringify({
email: "[email protected]", // Required
workflow_id: "your-workflow-id", // Required
cartItems: "<html>...</html>", // Optional custom data
couponCode: "SAVE20", // Optional custom data
orderTotal: "49.99" // Optional custom data
})
});
const result = await response.json();
console.log("Response:", result);
curl -X POST "https://yaplet.com/api/newsletter/workflow/start" \
-H "Content-Type: application/json" \
-H "Y-API-Key: YOUR_API_KEY" \
-d '{
"email": "[email protected]",
"workflow_id": "your-workflow-id",
"cartItems": "<html>...</html>",
"couponCode": "SAVE20",
"orderTotal": "49.99"
}'
<?php
$url = "https://yaplet.com/api/newsletter/workflow/start";
$headers = [
'Content-Type: application/json',
'Y-API-Key: YOUR_API_KEY'
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
"email" => "[email protected]", // Required
"workflow_id" => "your-workflow-id", // Required
"cartItems" => "<html>...</html>", // Optional custom data
"couponCode" => "SAVE20", // Optional custom data
"orderTotal" => "49.99" // Optional custom data
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode === 200) {
$result = json_decode($response, true);
echo "Response: " . print_r($result, true);
} else {
throw new Exception("Error: " . $response);
}
?>
import requests
url = "https://yaplet.com/api/newsletter/workflow/start"
headers = {
"Content-Type": "application/json",
"Y-API-Key": "YOUR_API_KEY"
}
response = requests.post(url, headers=headers, json={
"email": "[email protected]", # Required
"workflow_id": "your-workflow-id", # Required
"cartItems": "<html>...</html>", # Optional custom data
"couponCode": "SAVE20", # Optional custom data
"orderTotal": "49.99" # Optional custom data
})
if response.status_code == 200:
result = response.json()
print("Response:", result)
else:
raise Exception(f"Error: {response.text}")
Field Reference
Required Fields
| Field | Type | Description |
|---|---|---|
email | string | Email address of the subscriber. Must be a verified newsletter contact in your organization. |
workflow_id | string | UUID of the automation to start. The automation must be switched on and have its trigger set to Your app calls our API. |
Y-API-Key | header | API authentication key. Must be included in request headers. |
Optional Fields (Custom Data)
Any additional top-level fields in the request body are treated as custom data and passed into the automation. These values become available in later Send email and Send a webhook steps using {{key}} placeholders.
| Constraint | Limit |
|---|---|
| Maximum fields | 20 |
| Key type | Must be strings |
| Value type | Must be strings or numbers |
Using Custom Data in an Automation
Custom data sent via the API is available throughout the automation:
- Send email steps: Use
{{key}}placeholders in subject lines and email body content - Send a webhook steps: Include
{{key}}in webhook URLs and body values - If / else steps: These check the contact's own fields, groups and segments — they can't read the custom data you send
Example: If you send couponCode: "SAVE20" in your API call, you can use {{couponCode}} in your email template to display the coupon code to the subscriber.
Error Handling
Common Error Codes
| Code | Message | Description |
|---|---|---|
401 | API key is required in Y-API-Key header | Missing Y-API-Key header |
401 | Invalid API key | The provided API key doesn't match any key in the system |
403 | Unauthorized | The organization does not have the Email automations permission |
404 | Contact not found. Make sure the email is a verified newsletter contact. | The email is not a verified newsletter contact in your organization |
404 | Workflow not found. Make sure the workflow exists, is active, and has API trigger type. | The automation doesn't exist, is not switched on, or isn't set to the API trigger |
400 | Maximum of 20 custom fields allowed | Too many custom data fields in the request |
400 | Custom data values must be strings or numbers | Invalid custom data value type |
500 | Failed to start workflow | Unexpected server error |
Prerequisites
Before using this API, ensure:
- API key is generated - go to Settings → Connections → MCP & API keys to create one
- Contact exists and is verified - the subscriber email must be in your newsletter contacts with the Verified state
- The automation is switched on - the target automation must be switched On in the automation builder (its badge then reads Live)
- The automation uses the API trigger - its trigger must be set to Your app calls our API in the Trigger panel
Integration Best Practices
- Verify contacts first - make sure the contact exists before you start an automation for them; see Import / Export
- Handle errors gracefully - check response status codes and implement retry logic for 500 errors
- Avoid duplicate triggers - the API prevents duplicate pending runs, but design your integration to avoid unnecessary calls
- Keep custom data minimal - only send data your automation actually uses in its email or webhook steps
- Test with a single contact - verify your integration works correctly before scaling to production traffic