New: the MailCraft MCP server is live — connect your AI agent in one line. Connect your agent →
Start free
API reference

Automations

Multi-step sequences — send an email, wait, update the contact — started by a trigger or by enrolling contacts directly.

Create an automation

Creates a `draft` automation, optionally with its full step sequence in the same call. Step types: `send_email` (`template_id`, `sender_id` — a verified sender), `delay` (`duration_minutes`, 1–525600), `add_to_list` / `remove_from_list` (`list_id`), `update_property` (`key`, `value`) and `webhook` (`url`, a public HTTPS address). Triggers: `contact_created`, `contact_property_changed` (optional `trigger_config.property_key`), `added_to_list` (optional `trigger_config.list_id`), `manual` and `api`. Nothing runs until you activate it.

POST
/automations

Authorizations

Authorization
string
header
required

API key for your workspace, scoped to automations:manage. Pass it as a Bearer token in the Authorization header.

Body · application/json

name
string
trigger_type
string
steps
object[]
Create an automation
curl https://api.mailcraft.host/v1/automations \
  -X POST \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Welcome series",
    "trigger_type": "added_to_list",
    "trigger_config": { "list_id": 3 },
    "steps": [
      { "type": "send_email", "config": { "template_id": 9, "sender_id": 4 } },
      { "type": "delay", "config": { "duration_minutes": 4320 } },
      { "type": "send_email", "config": { "template_id": 10, "sender_id": 4 } }
    ]
  }'
{
  "data": {
    "id": 12,
    "name": "Welcome series",
    "status": "draft",
    "trigger_type": "added_to_list",
    "trigger_config": { "list_id": 3 },
    "steps": [
      { "id": 41, "position": 1, "type": "send_email", "config": { "template_id": 9, "sender_id": 4 } },
      { "id": 42, "position": 2, "type": "delay", "config": { "duration_minutes": 4320 } },
      { "id": 43, "position": 3, "type": "send_email", "config": { "template_id": 10, "sender_id": 4 } }
    ],
    "enrollment_counts": { "active": 0, "waiting": 0, "completed": 0, "exited": 0, "failed": 0 },
    "created_at": "2026-09-22T14:30:00.000000Z",
    "updated_at": "2026-09-22T14:30:00.000000Z"
  }
}

List automations

GET
/automations

Authorizations

Authorization
string
header
required

API key for your workspace, scoped to automations:manage. Pass it as a Bearer token in the Authorization header.

List automations
curl https://api.mailcraft.host/v1/automations \
  -H 'Authorization: Bearer sk_live_...'
{
  "data": [
    {
      "id": 12,
      "name": "Welcome series",
      "status": "active",
      "trigger_type": "added_to_list",
      "trigger_config": { "list_id": 3 },
      "created_at": "2026-09-22T14:30:00.000000Z",
      "updated_at": "2026-09-22T14:41:00.000000Z"
    }
  ]
}

Retrieve an automation

Includes the ordered steps and how many contacts are in each enrollment state.

GET
/automations/{automation}

Authorizations

Authorization
string
header
required

API key for your workspace, scoped to automations:manage. Pass it as a Bearer token in the Authorization header.

Retrieve an automation
curl https://api.mailcraft.host/v1/automations/12 \
  -H 'Authorization: Bearer sk_live_...'
{
  "data": {
    "id": 12,
    "name": "Welcome series",
    "status": "active",
    "trigger_type": "added_to_list",
    "trigger_config": { "list_id": 3 },
    "steps": [
      { "id": 41, "position": 1, "type": "send_email", "config": { "template_id": 9, "sender_id": 4 } }
    ],
    "enrollment_counts": { "active": 2, "waiting": 118, "completed": 740, "exited": 3, "failed": 0 },
    "created_at": "2026-09-22T14:30:00.000000Z",
    "updated_at": "2026-09-22T14:41:00.000000Z"
  }
}

Update an automation

Rename it or change its trigger — only the fields you send change. Pause an active automation before changing its trigger.

PATCH
/automations/{automation}

Authorizations

Authorization
string
header
required

API key for your workspace, scoped to automations:manage. Pass it as a Bearer token in the Authorization header.

Body · application/json

name
string
Update an automation
curl https://api.mailcraft.host/v1/automations/12 \
  -X PATCH \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Welcome series v2" }'
{
  "data": { "id": 12, "name": "Welcome series v2", "status": "draft", "...": "..." }
}

Replace the steps

Replaces the whole sequence — send every step, in order; omitted steps are removed. Returns `422` while the automation is active (pause it first) or while contacts are partway through it (remove them first).

PUT
/automations/{automation}/steps

Authorizations

Authorization
string
header
required

API key for your workspace, scoped to automations:manage. Pass it as a Bearer token in the Authorization header.

Body · application/json

steps
object[]
Replace the steps
curl https://api.mailcraft.host/v1/automations/12/steps \
  -X PUT \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "steps": [
      { "type": "send_email", "config": { "template_id": 9, "sender_id": 4 } },
      { "type": "update_property", "config": { "key": "onboarded", "value": true } }
    ]
  }'
{
  "data": {
    "id": 12,
    "steps": [
      { "id": 44, "position": 1, "type": "send_email", "config": { "template_id": 9, "sender_id": 4 } },
      { "id": 45, "position": 2, "type": "update_property", "config": { "key": "onboarded", "value": true } }
    ],
    "...": "..."
  }
}

Activate an automation

Starts enrolling contacts and running steps. Needs at least one step; the stored steps are re-validated first. Safe to repeat.

POST
/automations/{automation}/activate

Authorizations

Authorization
string
header
required

API key for your workspace, scoped to automations:manage. Pass it as a Bearer token in the Authorization header.

Activate an automation
curl https://api.mailcraft.host/v1/automations/12/activate \
  -X POST \
  -H 'Authorization: Bearer sk_live_...'
{
  "data": { "id": 12, "status": "active", "...": "..." }
}

Pause an automation

No new contacts enroll, and in-progress contacts wait where they are until it is activated again.

POST
/automations/{automation}/pause

Authorizations

Authorization
string
header
required

API key for your workspace, scoped to automations:manage. Pass it as a Bearer token in the Authorization header.

Pause an automation
curl https://api.mailcraft.host/v1/automations/12/pause \
  -X POST \
  -H 'Authorization: Bearer sk_live_...'
{
  "data": { "id": 12, "status": "paused", "...": "..." }
}

Enroll a contact

Starts an existing contact — by `contact_id` or `email` — on an active `manual` or `api` automation; its first steps run immediately. Returns `409` if the contact is already partway through it.

POST
/automations/{automation}/enrollments

Authorizations

Authorization
string
header
required

API key for your workspace, scoped to automations:manage. Pass it as a Bearer token in the Authorization header.

Body · application/json

email
string
Enroll a contact
curl https://api.mailcraft.host/v1/automations/12/enrollments \
  -X POST \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{ "email": "[email protected]" }'
{
  "data": {
    "id": 5021,
    "automation_id": 12,
    "contact_id": "01J8Z6Q4M7X2K9R3T5V8W1Y4ZB",
    "contact_email": "[email protected]",
    "status": "waiting",
    "current_step_id": 42,
    "resume_at": "2026-09-25T14:31:00.000000Z",
    "exited_reason": null,
    "enrolled_at": "2026-09-22T14:31:00.000000Z",
    "completed_at": null
  }
}

List enrollments

Newest first, cursor-paginated (`limit` up to 100). Filter with `status`: `active`, `waiting`, `completed`, `exited` or `failed`.

GET
/automations/{automation}/enrollments

Authorizations

Authorization
string
header
required

API key for your workspace, scoped to automations:manage. Pass it as a Bearer token in the Authorization header.

List enrollments
curl 'https://api.mailcraft.host/v1/automations/12/enrollments?status=waiting&limit=50' \
  -H 'Authorization: Bearer sk_live_...'
{
  "data": [
    {
      "id": 5021,
      "contact_email": "[email protected]",
      "status": "waiting",
      "resume_at": "2026-09-25T14:31:00.000000Z",
      "...": "..."
    }
  ],
  "links": { "next": "https://api.mailcraft.host/v1/automations/12/enrollments?cursor=eyJpZCI6NTAyMH0" },
  "meta": { "per_page": 50, "next_cursor": "eyJpZCI6NTAyMH0" }
}

Remove in-progress contacts

Takes every active or waiting contact out of the automation; they get no further steps. Needed before replacing the steps of an automation that has run.

DELETE
/automations/{automation}/enrollments

Authorizations

Authorization
string
header
required

API key for your workspace, scoped to automations:manage. Pass it as a Bearer token in the Authorization header.

Remove in-progress contacts
curl https://api.mailcraft.host/v1/automations/12/enrollments \
  -X DELETE \
  -H 'Authorization: Bearer sk_live_...'
{
  "data": { "exited": 120 }
}

Delete an automation

In-progress contacts are taken out first, so nothing is left half-run.

DELETE
/automations/{automation}

Authorizations

Authorization
string
header
required

API key for your workspace, scoped to automations:manage. Pass it as a Bearer token in the Authorization header.

Delete an automation
curl https://api.mailcraft.host/v1/automations/12 \
  -X DELETE \
  -H 'Authorization: Bearer sk_live_...'
(empty body)