Automation API

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.

API Key RequiredInclude the Y-API-Key header in all requests. Create and find your API key at Settings → Organization settings → API.

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 active with API trigger type.

The endpoint address, the workflow_id body field and the response messages all keep the word workflow. That is deliberate: the feature was renamed on screen from "Workflows" to "Email automations", but the wire names were left alone so existing integrations carry on working untouched. 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"
}

Important: Custom data fields are sent as top-level fields alongside 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 active and have API trigger type.
`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 subsequent Email and Webhook nodes using {{key}} placeholders.

Constraint	Limit
Maximum fields	20
Key type	Must be strings
Value type	Must be strings or numbers

Custom data values are sanitized for security. HTML content is allowed but will be cleaned to prevent XSS attacks.

Using Custom Data in an Automation

Custom data sent via the API is available throughout the automation:

Email nodes: Use {{key}} placeholders in subject lines and email body content
Webhook nodes: Include {{key}} in webhook URLs and body values
Condition nodes: Evaluate custom data values for branching logic

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 (`Newsletter.Automations`)
`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 active, 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 → Organization settings → API to create one
Contact exists and is verified - the subscriber email must be in your newsletter contacts with "VERIFIED" status
The automation is active - the target automation must be switched to Active in the automation builder
The automation uses the API trigger - its trigger type must be set to API in the trigger settings

If the subscriber email is not found or not verified, you'll receive a 404 error. Make sure contacts are imported and verified before starting automations for them.

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 email or webhook nodes
Test with a single contact - verify your integration works correctly before scaling to production traffic