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.

API Key RequiredInclude the 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.

The endpoint address, the 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"
}
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);

Field Reference

Required Fields

FieldTypeDescription
emailstringEmail address of the subscriber. Must be a verified newsletter contact in your organization.
workflow_idstringUUID of the automation to start. The automation must be switched on and have its trigger set to Your app calls our API.
Y-API-KeyheaderAPI 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.

ConstraintLimit
Maximum fields20
Key typeMust be strings
Value typeMust 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:

  • 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

CodeMessageDescription
401API key is required in Y-API-Key headerMissing Y-API-Key header
401Invalid API keyThe provided API key doesn't match any key in the system
403UnauthorizedThe organization does not have the Email automations permission
404Contact not found. Make sure the email is a verified newsletter contact.The email is not a verified newsletter contact in your organization
404Workflow 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
400Maximum of 20 custom fields allowedToo many custom data fields in the request
400Custom data values must be strings or numbersInvalid custom data value type
500Failed to start workflowUnexpected server error

Prerequisites

Before using this API, ensure:

  1. API key is generated - go to Settings → Connections → MCP & API keys to create one
  2. Contact exists and is verified - the subscriber email must be in your newsletter contacts with the Verified state
  3. The automation is switched on - the target automation must be switched On in the automation builder (its badge then reads Live)
  4. The automation uses the API trigger - its trigger must be set to Your app calls our API in the Trigger panel
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

  1. Verify contacts first - make sure the contact exists before you start an automation for them; see Import / Export
  2. Handle errors gracefully - check response status codes and implement retry logic for 500 errors
  3. Avoid duplicate triggers - the API prevents duplicate pending runs, but design your integration to avoid unnecessary calls
  4. Keep custom data minimal - only send data your automation actually uses in its email or webhook steps
  5. Test with a single contact - verify your integration works correctly before scaling to production traffic

© 2026 Yaplet. All rights reserved.