Workflow API | Yaplet

Overview

The Workflow Start API lets you trigger newsletter workflows programmatically for specific subscribers. This is useful for starting automated sequences from your e-commerce platform, CRM, or any external system when specific events occur (e.g., abandoned cart, new purchase, account activity).

Authentication

All API requests require authentication using your API key.

API Key RequiredInclude the Y-API-Key header in all requests. You can find your API key in the dashboard settings under Settings > API.

Endpoint Details

POST `https://yaplet.com/api/newsletter/workflow/start`

Starts a workflow for a specific subscriber. The subscriber must be a verified newsletter contact in your organization, and the workflow must be active with API trigger type.

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 workflow, 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 workflow to start. The workflow 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 workflow. 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 Workflows

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

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	Organization doesn't have the Newsletter Workflows permission
`404`	Contact not found	The email is not a verified newsletter contact in your organization
`404`	Workflow not found	The workflow doesn't exist, is not active, or doesn't have API trigger type
`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 > API to create one
Contact exists and is verified - The subscriber email must be in your newsletter contacts with "VERIFIED" status
Workflow is active - The target workflow must be activated in the workflow editor
Workflow has API trigger - The workflow's 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 triggering workflows for them.

Integration Best Practices

Verify contacts first - Use the Bulk Upsert API to ensure contacts exist before starting workflows
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 that your workflow actually uses in email or webhook nodes
Test with a single contact - Verify your integration works correctly before scaling to production traffic