API Reference

Mails.now API Reference

Provision domains and mailboxes, manage sequencer campaigns and leads, and automate with webhooks — all via the Mails.now REST API.

Authentication & Conventions

Use header-based authentication only: Authorization: Bearer <key> or X-Api-Key: <key>.

Base URL

https://mails.now/api

API Key Format

32 characters (alpha-numeric)

Queue Behavior

Background jobs return a `task_id`.
Poll the matching get-task endpoint until `completed` or `failed`.
Bulk domain deletes: up to 10 hostnames per request.
Bulk mailbox deletes: up to 100 addresses per request.
One bulk-delete request per 5 minutes per API key and IP.
HTTP 422 validation errors do not count toward the cooldown.
Active pricing plan required (admins exempt).

Success Contract

{
    "status": "success"
}

Error Contract

{
    "status": "error",
    "reason": "Error description"
}

POST

/api/v1/create/domain

Create Domain

Creates a new base domain in your Mails.now workspace and queues provisioning in the background.

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key`.

Field	Type	Required	Description
Domain	string	Yes	Fully qualified hostname (e.g. example.com). Omit http(s)://; single-label names are rejected (same rules as the dashboard Add domain form).
Params	object	No	Optional keys (for example `total_mailbox_allowed`).
Params.total_mailbox_allowed	integer	No	Mailbox slots recorded for the domain (minimum 1, maximum 100; defaults to the app maximum per hostname).

Request Example

curl --fail-with-body --silent --show-error \
  -X POST "{{ url('/api/v1/create/domain') }}" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Domain": "example.com",
    "Params": {
      "total_mailbox_allowed": 100
    }
  }'

Success Response

{
    "status": "success",
    "domain": "example.com",
    "task_id": 101
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - An active pricing plan is required before you can create domains, subdomains, or mailboxes via the API.
HTTP 409 - This domain is already registered on Mails.now.
HTTP 422 - First validation error message (invalid body fields).

Notes

Invalid hostnames return HTTP 422 before enqueue; duplicates return HTTP 409.
Poll `GET /api/v1/get/domain?task_id=…`. When `completed`, `results` includes DNS `records` (MX/TXT/A).
Remote mail server defaults apply on provision; quota fields are not accepted on this request.

GET

/api/v1/get/domain?task_id={task_id}

Get Domain Task

Polls a root domain create task created by `POST /api/v1/create/domain`.

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key`.

Field	Type	Required	Description
task_id	integer	Yes	Task identifier returned by Create Domain.

Request Example

curl --fail-with-body --silent --show-error \
  "{{ url('/api/v1/get/domain') }}?task_id=101" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "Task_id": 101,
    "total_email": 0,
    "domain": "example.com",
    "results": {
        "domain": "example.com",
        "status": "Created successfully.",
        "records": [
            {
                "type": "MX",
                "name": "example.com",
                "value": "mx1.mails.now",
                "priority": "10",
                "status": "Not checked"
            },
            {
                "type": "MX",
                "name": "example.com",
                "value": "mx2.mails.now",
                "priority": "20",
                "status": "Not checked"
            },
            {
                "type": "TXT",
                "name": "_mailapi.example.com",
                "value": "<generated-unique-token>",
                "priority": "\u2014",
                "status": "Not checked"
            }
        ]
    },
    "status": "completed",
    "task_id": "101"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 404 - Task ID was not found for this API key.
HTTP 422 - Task type does not match this endpoint.
HTTP 422 - Dynamic failure message from the queue job (same shape as other errors).

Notes

`status` may be `queued`, `running`, `completed`, or `failed`. Only `failed` returns HTTP 422 with `reason` from the task.
While `queued` or `running`, `results` is often an empty array until the job finishes.
Responses include `Task_id` (integer) and `task_id` (same value as a string).

POST

/api/v1/create/sub-domain

Create Sub-Domain Batch

Creates up to 10 sub-domains under an existing parent domain in a single queued task.

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key`.

Field	Type	Required	Description
Domain	string	Yes	Existing parent (root) domain owned by your account. Must be a valid dotted hostname (same rules as Create Domain / dashboard).
Params.sub_domains	string[]	Yes	Sub-domain labels (not FQDN), max 10 per request.
Params.total_mailbox_allowed	integer	No	Mailbox slots per created hostname (min 1, max 100; defaults to the app maximum per hostname).

Request Example

curl --fail-with-body --silent --show-error \
  -X POST "{{ url('/api/v1/create/sub-domain') }}" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Domain": "example.com",
    "Params": {
      "sub_domains": ["team", "support", "billing"]
    }
  }'

Success Response

{
    "status": "success",
    "domain": "example.com",
    "task_id": 202
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - An active pricing plan is required before you can create domains, subdomains, or mailboxes via the API.
HTTP 404 - Parent domain was not found.
HTTP 422 - Params.sub_domains must be a non-empty array (or validation on labels).
HTTP 422 - Maximum 10 sub-domains are allowed per request.
HTTP 429 - Sub-domain requests are limited to once per 2 minutes for this domain and API key.

Notes

After a successful run: at most one request per 2 minutes per API key and parent domain.
Poll `GET /api/v1/get/sub-domain?task_id=…`. When `completed`, nested `results` are keyed by FQDN.
Provisioning uses the same remote defaults as Create Domain; quota fields are not accepted.

GET

/api/v1/get/sub-domain?task_id={task_id}

Get Sub-Domain Task

Polls a sub-domain batch task from `POST /api/v1/create/sub-domain`.

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key`.

Field	Type	Required	Description
task_id	integer	Yes	Task identifier returned by Create Sub-Domain.

Request Example

curl --fail-with-body --silent --show-error \
  "{{ url('/api/v1/get/sub-domain') }}?task_id=202" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "Task_id": 202,
    "total_email": 0,
    "domain": "example.com",
    "results": {
        "domain": "example.com",
        "results": {
            "team.example.com": {
                "status": "Created successfully.",
                "records": [
                    {
                        "type": "MX",
                        "name": "team.example.com",
                        "value": "mx1.mails.now",
                        "priority": "10",
                        "status": "Not checked"
                    },
                    {
                        "type": "MX",
                        "name": "team.example.com",
                        "value": "mx2.mails.now",
                        "priority": "20",
                        "status": "Not checked"
                    }
                ]
            },
            "support.example.com": {
                "status": "Created successfully.",
                "records": [
                    {
                        "type": "MX",
                        "name": "support.example.com",
                        "value": "mx1.mails.now",
                        "priority": "10",
                        "status": "Not checked"
                    },
                    {
                        "type": "MX",
                        "name": "support.example.com",
                        "value": "mx2.mails.now",
                        "priority": "20",
                        "status": "Not checked"
                    }
                ]
            }
        }
    },
    "status": "completed",
    "task_id": "202"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 404 - Task ID was not found for this API key.
HTTP 422 - Task type does not match this endpoint.
HTTP 422 - Dynamic failure message from provisioning.

Notes

`status` values are the same as other task endpoints (`queued`, `running`, `completed`, `failed`).
Responses include `Task_id` (integer) and `task_id` (same value as a string).

GET

/api/v1/list/domain

List Domains

Returns all domains for the API key owner account, keyed by domain name.

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key`.

Field	Type	Required	Description

Request Example

curl --fail-with-body --silent --show-error \
  "{{ url('/api/v1/list/domain') }}" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "total_domain": 2,
    "results": {
        "example.com": {
            "status": "verified",
            "domain_type": "root",
            "domain_quota": "0GB",
            "mailbox_count": "15",
            "created_at": "14-04-2026"
        },
        "team.example.com": {
            "status": "verified",
            "domain_type": "sub",
            "domain_quota": "0GB",
            "mailbox_count": "3",
            "created_at": "15-04-2026"
        }
    },
    "status": "success"
}

Error Responses

HTTP 401 - Invalid API key.

Notes

`domain_type` is `root` or `sub`.
`domain_quota` is a string with a `GB` suffix; `0GB` means unlimited in list responses (non-zero may appear on older rows).

POST

/api/v1/delete/domain/bulk

Bulk Delete Domains

Queues removal of up to 10 domains (root or sub-domain hostnames) owned by your account. Deletes run sequentially on the mail server; there is no artificial delay between items.

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key` with `write` permission.

Field	Type	Required	Description
Domains	string[]	Yes	Fully qualified hostnames to remove (1–10 per request). Duplicates are rejected. Same hostname rules as create domain (no scheme; valid dotted hostname).

Request Example

curl --fail-with-body --silent --show-error \
  -X POST "{{ url('/api/v1/delete/domain/bulk') }}" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Domains": ["old.example.com", "legacy.example.com"]
  }'

Success Response

{
    "status": "success",
    "task_id": 801
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - An active pricing plan is required before you can create, bulk-delete, or manage domains, subdomains, or mailboxes via the API.
HTTP 422 - Validation error (empty array, too many domains, invalid hostname, or duplicate entries).
HTTP 429 - Too many requests (bulk domain delete is limited to one successfully enqueued call per 5 minutes per API key and IP).

Notes

Cooldown: one successfully enqueued call per 5 minutes per API key and IP; HTTP 422 does not count. Mailbox bulk delete uses a separate counter of the same length.
Poll `GET /api/v1/get/delete/domain/bulk?task_id=…` until `completed` or `failed`.
When `completed`, `results` entries use `deleted`, `failed`, or `skipped` with optional `reason`; partial failures still yield task `completed`.
Deleting a root domain removes descendant hostnames and their mailboxes in dependency order.

GET

/api/v1/get/delete/domain/bulk?task_id={task_id}

Get Bulk Delete Domains Task

Polls a bulk domain delete task created by `POST /api/v1/delete/domain/bulk`.

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key` with `read` permission.

Field	Type	Required	Description
task_id	integer	Yes	Task identifier returned by Bulk Delete Domains.

Request Example

curl --fail-with-body --silent --show-error \
  "{{ url('/api/v1/get/delete/domain/bulk') }}?task_id=801" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "Task_id": 801,
    "total_email": 0,
    "domain": "old.example.com",
    "results": {
        "old.example.com": {
            "status": "deleted"
        },
        "legacy.example.com": {
            "status": "failed",
            "reason": "Mail server rejected domain removal."
        },
        "missing.example.com": {
            "status": "skipped",
            "reason": "Domain not found for this account."
        }
    },
    "status": "completed",
    "task_id": "801"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 404 - Task ID was not found for this API key.
HTTP 422 - Task type does not match this endpoint.
HTTP 422 - Dynamic failure message from `error_message` when the task fails.

Notes

`status` may be `queued`, `running`, `completed`, or `failed`. Only `failed` (task-level) returns HTTP 422 with `reason` from the task.
Per-domain outcomes (`deleted`, `failed`, or `skipped`) appear inside `results` while the overall task can still be `completed`.

POST

/api/v1/create/mailbox/single

Create Single Mailbox

Queues one mailbox creation request for a domain that belongs to your account.

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key`.

Field	Type	Required	Description
Email_fullname	string	Yes	Display name stored on the mailbox (not the email local-part).
single_bulk	string	Yes	Must be `single`.
Domain	string	Yes	Target domain hostname.
Params	object	Yes	Payload object for mailbox provisioning details.
Params.email_id	string	Yes	Mailbox address. Must belong to the provided Domain.
Params.password	string\|integer	Yes	Mailbox password string (minimum 8 characters) or numeric `0` to auto-generate a secure password (20+ chars).
Params.reputation_level_id	integer	No	Optional active reputation level ID to assign at create.
Params.send_pattern_id	integer	No	Optional send pattern ID owned by the API key user (see List Send Patterns). Patterns assigned to mailboxes cannot be deleted in Settings until reassigned.
Params.sender_signature_id	integer	No	Optional sender settings (signature) ID owned by the API key user (see List Sender Signatures). Signatures assigned to mailboxes cannot be deleted in Settings until reassigned.

Request Example

curl --fail-with-body --silent --show-error \
  -X POST "{{ url('/api/v1/create/mailbox/single') }}" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Email_fullname": "John Doe",
    "single_bulk": "single",
    "Domain": "example.com",
    "Params": {
      "email_id": "john@example.com",
      "password": 0
    }
  }'

Success Response

{
    "status": "success",
    "task_id": 123
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - An active pricing plan is required before you can create domains, subdomains, or mailboxes via the API.
HTTP 404 - Domain not found for this account.
HTTP 422 - First validation error message (invalid body fields).

Notes

Invalid bodies return HTTP 422 before enqueue. Only numeric `0` for `Params.password` triggers auto-generation (string `"0"` is rejected).
Poll `GET /api/v1/get/mailbox/single?task_id=…`; remote failures return HTTP 422 on that poll.
Create and manage send patterns / sender signatures in the dashboard Settings pages. Use List Send Patterns and List Sender Signatures to discover IDs for assignment.

POST

/api/v1/create/mailbox/bulk

Create Bulk Mailboxes

Queues a bulk mailbox provisioning task and returns a task ID for later retrieval.

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key`.

Field	Type	Required	Description
Email_fullname	string	Yes	Display name used with internal rules to derive unique mailbox local-parts.
single_bulk	string	Yes	Must be `bulk`.
Domain	string	Yes	Target domain hostname.
Params	object	Yes	Payload object for mailbox provisioning details.
Params.mailbox_no	integer	Yes	How many mailboxes to create (must be between 1 and 100).
Params.password	string\|integer	Yes	Shared password string for the batch (minimum 8 characters), or numeric `0` to generate a unique secure password (20+ chars) per mailbox.
Params.reputation_level_id	integer	No	Optional active reputation level ID applied to every mailbox in the batch.
Params.send_pattern_id	integer	No	Optional send pattern ID owned by the API key user; applied to every mailbox in the batch. Patterns assigned to mailboxes cannot be deleted in Settings until reassigned.
Params.sender_signature_id	integer	No	Optional sender settings (signature) ID owned by the API key user; applied to every mailbox in the batch. Signatures assigned to mailboxes cannot be deleted in Settings until reassigned.

Request Example

curl --fail-with-body --silent --show-error \
  -X POST "{{ url('/api/v1/create/mailbox/bulk') }}" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Email_fullname": "Team Member",
    "single_bulk": "bulk",
    "Domain": "example.com",
    "Params": {
      "mailbox_no": 25,
      "password": 0
    }
  }'

Success Response

{
    "status": "success",
    "task_id": 456
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - An active pricing plan is required before you can create domains, subdomains, or mailboxes via the API.
HTTP 404 - Domain not found for this account.
HTTP 422 - First validation error message (invalid body fields).
HTTP 429 - Bulk mailbox requests are limited to once per 2 minutes for this domain and API key.

Notes

After a successful run: at most one bulk create per 2 minutes per API key and target hostname.
`Params.mailbox_no` must be between 1 and 100.
If a generated mailbox address already exists, it is skipped and the task continues creating the remaining addresses.
If all requested addresses already exist, the task still completes successfully with `total_email` set to `0` and an empty `results` object.
Only numeric `0` for `Params.password` triggers per-mailbox auto-generation (string `"0"` is rejected).
Poll `GET /api/v1/get/mailbox/bulk?task_id=…`; remote failures return HTTP 422 on that poll.

GET

/api/v1/get/mailbox/single?task_id={task_id}

Get Single Mailbox Task

Fetches status and final result for a single mailbox provisioning task.

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key`.

Field	Type	Required	Description
task_id	integer	Yes	Task identifier returned by create endpoint.

Request Example

curl --fail-with-body --silent --show-error \
  "{{ url('/api/v1/get/mailbox/single') }}?task_id=123" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "Task_id": 123,
    "total_email": 1,
    "domain": "example.com",
    "results": {
        "john@example.com": {
            "email": "john@example.com",
            "password": "SecurePass123",
            "quota": "0MB",
            "domain": "example.com",
            "provisioning": "pending",
            "create_date": "2026-04-26 16:45:00"
        }
    },
    "status": "completed",
    "task_id": "123"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 404 - Task ID was not found for this API key.
HTTP 422 - Task type does not match this endpoint.
HTTP 422 - Dynamic failure message from `error_message` when the task fails.

Notes

`status` is `queued`, `running`, `completed`, or `failed`. While pending, `results` is often empty.
Both `Task_id` (int) and `task_id` (string) are returned with the same value.
When `completed`, each entry includes `email`, `password`, `quota`, `domain`, `provisioning`, `create_date`, reputation fields, `send_pattern_id`, and `sender_signature_id` (no per-entry `status`).
If create used `Params.password: 0`, the response `password` is generated per mailbox.

GET

/api/v1/get/mailbox/bulk?task_id={task_id}

Get Bulk Mailbox Task

Fetches status and per-mailbox results for a bulk mailbox provisioning task.

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key`.

Field	Type	Required	Description
task_id	integer	Yes	Task identifier returned by bulk create endpoint.

Request Example

curl --fail-with-body --silent --show-error \
  "{{ url('/api/v1/get/mailbox/bulk') }}?task_id=456" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "Task_id": 456,
    "total_email": 25,
    "domain": "example.com",
    "results": {
        "team1@example.com": {
            "status": "Created successfully.",
            "password": "kL4!pQ9#uD2@xM7&zT8w"
        },
        "team2@example.com": {
            "status": "Created successfully.",
            "password": "rN6$hS1*eV0!cB3%yK5m"
        }
    },
    "status": "completed",
    "task_id": "456"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 404 - Task ID was not found for this API key.
HTTP 422 - Task type does not match this endpoint.
HTTP 422 - Dynamic failure message from `error_message` when the task fails.

Notes

`status` follows the same lifecycle as single mailbox tasks.
Responses include `Task_id` (integer) and `task_id` (same value as a string).
When some requested addresses already exist, those addresses are skipped and `total_email` reflects only newly created mailboxes.
If all requested addresses already exist, the task still completes successfully with `total_email` set to `0` and an empty `results` object.
Results include mailbox-by-mailbox status details when `completed`.
If bulk create used numeric `Params.password: 0`, each mailbox result includes its own generated `password` value.

POST

/api/v1/delete/mailbox/bulk

Bulk Delete Mailboxes

Queues removal of up to 100 mailbox addresses owned by your account. Deletes run sequentially; there is no artificial delay between items.

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key` with `write` permission.

Field	Type	Required	Description
Mailboxes	string[]	Yes	Full RFC email addresses (1–100 per request). Duplicates are rejected.

Request Example

curl --fail-with-body --silent --show-error \
  -X POST "{{ url('/api/v1/delete/mailbox/bulk') }}" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Mailboxes": ["a@example.com", "b@example.com"]
  }'

Success Response

{
    "status": "success",
    "task_id": 802
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - An active pricing plan is required before you can create, bulk-delete, or manage domains, subdomains, or mailboxes via the API.
HTTP 422 - Validation error (empty array, too many addresses, invalid email, or duplicate entries).
HTTP 429 - Too many requests (bulk mailbox delete is limited to one successfully enqueued call per 5 minutes per API key and IP).

Notes

Cooldown: one successfully enqueued call per 5 minutes per API key and IP; HTTP 422 does not count. Domain bulk delete uses a separate counter of the same length.
Poll `GET /api/v1/get/delete/mailbox/bulk?task_id=…` until `completed` or `failed`.
When `completed`, `results` entries use `deleted`, `failed`, or `skipped` with optional `reason`.

GET

/api/v1/get/delete/mailbox/bulk?task_id={task_id}

Get Bulk Delete Mailboxes Task

Polls a bulk mailbox delete task created by `POST /api/v1/delete/mailbox/bulk`.

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key` with `read` permission.

Field	Type	Required	Description
task_id	integer	Yes	Task identifier returned by Bulk Delete Mailboxes.

Request Example

curl --fail-with-body --silent --show-error \
  "{{ url('/api/v1/get/delete/mailbox/bulk') }}?task_id=802" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "Task_id": 802,
    "total_email": 2,
    "domain": "example.com",
    "results": {
        "a@example.com": {
            "status": "deleted"
        },
        "b@example.com": {
            "status": "failed",
            "reason": "Mail server rejected mailbox removal."
        },
        "gone@example.com": {
            "status": "skipped",
            "reason": "Mailbox not found for this account."
        }
    },
    "status": "completed",
    "task_id": "802"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 404 - Task ID was not found for this API key.
HTTP 422 - Task type does not match this endpoint.
HTTP 422 - Dynamic failure message from `error_message` when the task fails.

Notes

`total_email` mirrors the request size (count of addresses submitted), not the number successfully deleted.
Per-mailbox outcomes (`deleted`, `failed`, or `skipped`) appear inside `results` while the overall task can still be `completed`.

GET

/api/v1/list/mailbox?domain={domain}&include_credentials={0|1}

List Mailboxes

Returns all mailboxes for a specific owned domain, keyed by full email address.

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key`.

Field	Type	Required	Description
domain	string	Yes	Domain to list mailboxes for.
include_credentials	boolean	No	Include `imap_credentials` in each mailbox result when true.

Request Example

curl --fail-with-body --silent --show-error \
  "{{ url('/api/v1/list/mailbox') }}?domain=example.com&include_credentials=1" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "domain": "example.com",
    "results": {
        "john@example.com": {
            "provisioning_status": "active",
            "mailbox_quota": "0MB",
            "imap_credentials": {
                "host": "imap.example.com",
                "port": 993,
                "encryption": "tls"
            },
            "created_at": "14-04-2026",
            "reputation_level_id": 1,
            "level_name": "Starter",
            "daily_send_limit": 20,
            "hourly_send_limit": 5,
            "per_minute_send_limit": 1,
            "send_pattern_id": null,
            "sender_signature_id": null
        }
    },
    "status": "success"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 404 - Domain not found for this account.

Notes

`imap_credentials` only when `include_credentials=true`.
`mailbox_quota` is a string with an `MB` suffix; `0MB` means unlimited (non-zero may appear on older rows).
Each mailbox result includes `reputation_level_id`, `level_name`, send limits, `send_pattern_id`, and `sender_signature_id` (nullable).

GET

/api/v1/list/send-pattern

List Send Patterns

Returns send patterns owned by the API key user, including how many mailboxes currently use each pattern.

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key`.

Field	Type	Required	Description

Request Example

curl --fail-with-body --silent --show-error \
  "{{ url('/api/v1/list/send-pattern') }}" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "total": 1,
    "results": [
        {
            "id": 12,
            "name": "Warm mailbox",
            "daily_send_limit": 20,
            "ramp_up_percent_per_day": 10,
            "ramp_up_mode": "percent",
            "max_send_limit": 100,
            "send_interval_seconds": 45,
            "assigned_mailbox_count": 2
        }
    ],
    "status": "success"
}

Error Responses

HTTP 401 - Invalid API key.

Notes

Create and edit patterns in Settings → Send Pattern. Patterns with `assigned_mailbox_count` > 0 cannot be deleted until mailboxes are reassigned.
Use `id` as `Params.send_pattern_id` when creating mailboxes.

GET

/api/v1/list/sender-signature

List Sender Signatures

Returns sender settings (signatures) owned by the API key user, including how many mailboxes currently use each signature.

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key`.

Field	Type	Required	Description

Request Example

curl --fail-with-body --silent --show-error \
  "{{ url('/api/v1/list/sender-signature') }}" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "total": 1,
    "results": [
        {
            "id": 8,
            "name": "Work signature",
            "reply_to_email": "replies@example.com",
            "first_name": "Alex",
            "last_name": "Sender",
            "from_name": "Alex Sender",
            "assigned_mailbox_count": 1
        }
    ],
    "status": "success"
}

Error Responses

HTTP 401 - Invalid API key.

Notes

Create and edit signatures in Settings → Sender Settings. Signatures with `assigned_mailbox_count` > 0 cannot be deleted until mailboxes are reassigned.
Use `id` as `Params.sender_signature_id` when creating mailboxes.

POST

/api/v1/create/alias

Create Alias

Queues an alias or forwarder. `goto` can be a local mailbox or external address(es). Use `Params.catch_all=true` for @domain catch-all.

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key`.

Field	Type	Required	Description
Domain	string	Yes	Owned domain hostname.
Params.address	string	Yes	Alias address on the domain (omit when catch_all is true).
Params.goto	string\|array	Yes	Destination mailbox or external email(s). Comma-separated string or JSON array.
Params.catch_all	boolean	No	Create catch-all `@domain`.
Params.sender_allowed	boolean	No	Allow sending as this alias (send-as).

Request Example

curl --fail-with-body --silent --show-error \
  -X POST "{{ url('/api/v1/create/alias') }}" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Domain": "example.com",
    "Params": {
      "address": "sales@example.com",
      "goto": "team@example.com"
    }
  }'

Success Response

{
    "status": "success",
    "task_id": 123
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 404 - Domain not found for this account.
HTTP 422 - Alias already exists / goto invalid / plan limit reached.

Notes

Poll `GET /api/v1/get/alias?task_id=` for completion.
External destinations are forwarders; local mailbox destinations are aliases.

POST

/api/v1/create/alias/bulk

Create Bulk Aliases

Queues multiple aliases in one task via `Params.aliases`.

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key`.

Field	Type	Required	Description
Domain	string	Yes	Owned domain hostname.
Params.aliases	array	Yes	Array of `{address, goto}` objects.

Request Example

curl --fail-with-body --silent --show-error \
  -X POST "{{ url('/api/v1/create/alias/bulk') }}" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Domain": "example.com",
    "Params": {
      "aliases": [
        {"address": "a@example.com", "goto": "team@example.com"},
        {"address": "b@example.com", "goto": "ops@gmail.com"}
      ]
    }
  }'

Success Response

{
    "status": "success",
    "task_id": 124
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 422 - Validation or capacity error.

Notes

Poll `GET /api/v1/get/alias?task_id=`.

POST

/api/v1/edit/alias

Edit Alias

Queues an update for an existing alias (`goto`, `active`, `sender_allowed`).

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key`.

Field	Type	Required	Description
address	string	Yes	Existing alias address.
goto	string\|array	No	Updated destination(s).
active	boolean	No	Enable or disable the alias.
sender_allowed	boolean	No	Allow sending as this alias.

Request Example

curl --fail-with-body --silent --show-error \
  -X POST "{{ url('/api/v1/edit/alias') }}" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "sales@example.com",
    "goto": "newteam@example.com",
    "active": true
  }'

Success Response

{
    "status": "success",
    "task_id": 125
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 422 - Alias not found or goto invalid.

Notes

Poll `GET /api/v1/get/alias?task_id=`.

GET

/api/v1/get/alias?task_id={id}

Get Alias Task

Poll create/edit/bulk alias task status.

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key`.

Field	Type	Required	Description
task_id	integer	Yes	Task id from create/edit endpoints.

Request Example

curl --fail-with-body --silent --show-error \
  "{{ url('/api/v1/get/alias') }}?task_id=123" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "Task_id": 123,
    "status": "completed",
    "results": [],
    "task_id": "123"
}

Error Responses

HTTP 404 - Task ID was not found for this API key.
HTTP 422 - Task type does not match this endpoint.

Notes

GET

/api/v1/list/alias?domain={domain}

List Aliases

Lists aliases for an owned domain.

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key`.

Field	Type	Required	Description
domain	string	Yes	Domain hostname.

Request Example

curl --fail-with-body --silent --show-error \
  "{{ url('/api/v1/list/alias') }}?domain=example.com" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "domain": "example.com",
    "results": {
        "sales@example.com": {
            "goto": [
                "team@example.com"
            ],
            "active": true,
            "is_catch_all": false,
            "provisioning_status": "active"
        }
    },
    "status": "success"
}

Error Responses

HTTP 404 - Domain not found for this account.

Notes

POST

/api/v1/delete/alias/bulk

Bulk Delete Aliases

Queues deletion of one or more aliases by address.

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key`.

Field	Type	Required	Description
Aliases	array	Yes	Alias addresses to delete.

Request Example

curl --fail-with-body --silent --show-error \
  -X POST "{{ url('/api/v1/delete/alias/bulk') }}" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Aliases": ["sales@example.com"]
  }'

Success Response

{
    "status": "success",
    "task_id": 126
}

Error Responses

HTTP 429 - Bulk delete cooldown.

Notes

Poll `GET /api/v1/get/delete/alias/bulk?task_id=`.

GET

/api/v1/get/delete/alias/bulk?task_id={id}

Get Bulk Delete Aliases Task

Poll bulk alias delete task status.

Header auth required: `Authorization: Bearer <key>` or `X-Api-Key`.

Field	Type	Required	Description
task_id	integer	Yes	Task id from delete endpoint.

Request Example

curl --fail-with-body --silent --show-error \
  "{{ url('/api/v1/get/delete/alias/bulk') }}?task_id=126" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "Task_id": 126,
    "status": "completed",
    "results": [],
    "task_id": "126"
}

Error Responses

HTTP 404 - Task ID was not found for this API key.

Notes

POST

/api/v1/mail/inbound

Inbound Email

Accepts inbound payloads for a tenant mailbox and queues processing. Optional fields include `from_name`, `cc`, `bcc`, `body_html`, `attachments`, and `headers`.

Requires API key with `inbound` permission.

Field	Type	Required	Description
message_id	string	Yes	Upstream message identifier. Must be unique per mailbox.
from_email	string	Yes	Sender email address.
to_email	string	Yes	Recipient mailbox address owned by your tenant.
subject	string	Yes	Email subject line.
received_at	ISO datetime	Yes	Inbound receive timestamp.

Request Example

curl --fail-with-body --silent --show-error \
  -X POST "{{ url('/api/v1/mail/inbound') }}" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": "<mail-message-id>",
    "from_email": "sender@example.com",
    "to_email": "user@example.com",
    "subject": "Hello",
    "body_text": "Body",
    "received_at": "2026-04-28T10:00:00Z"
  }'

Success Response

{
    "status": "accepted",
    "message_id": "<mail-message-id>"
}

Error Responses

HTTP 401 - API key is required or invalid.
HTTP 403 - API key lacks inbound permission.
HTTP 409 - Duplicate message_id.
HTTP 422 - Unknown mailbox or invalid payload.

Notes

Inbound processing is asynchronous.

GET

/api/v1/emails

List Emails

Returns tenant-scoped inbox emails with cursor pagination.

Requires API key with `read` permission.

Field	Type	Required	Description
mailbox_id	integer	No	Filter by mailbox.
unread	boolean	No	Return unread only.
since	ISO datetime	No	Filter received_at lower bound.
before	ISO datetime	No	Filter received_at upper bound.
q	string	No	Search subject, body text, or sender address.

Request Example

curl "{{ url('/api/v1/emails?unread=1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "data": [],
    "meta": {
        "next_cursor": null,
        "prev_cursor": null
    }
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - API key lacks read permission.

Notes

Query is always tenant-isolated.

GET

/api/v1/emails/{email}

Get Email

Returns one tenant-scoped email with attachment metadata.

Requires API key with `read` permission.

Field	Type	Required	Description
email	integer	Yes	Email record ID (route parameter `{email}`).

Request Example

curl "{{ url('/api/v1/emails/123') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "data": {
        "id": 123
    }
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 404 - Email not found in your tenant scope.

Notes

Soft-deleted records are not returned from this endpoint.

GET

/api/v1/emails/sync?since=ISO_TIMESTAMP

Sync Emails

Incremental polling endpoint for new, updated, and deleted emails.

Requires API key with `read` permission.

Field	Type	Required	Description
since	ISO datetime	Yes	Sync lower bound using updated markers.

Request Example

curl "{{ url('/api/v1/emails/sync?since=2026-04-28T00:00:00Z') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "data": [],
    "meta": {
        "next_cursor": null,
        "prev_cursor": null
    }
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 422 - The since field is required and must be a valid date.

Notes

Deleted emails are returned with deletion markers to support tombstones.

POST

/api/v1/emails/{email}/read

Mark Email Read

Marks an email as read and emits an email.read webhook event.

Requires API key with `write` permission.

Field	Type	Required	Description
email	integer	Yes	Email record ID (route parameter `{email}`).

Request Example

curl -X POST "{{ url('/api/v1/emails/123/read') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "status": "success"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - API key lacks write permission.
HTTP 404 - Email not found in your tenant scope.

Notes

This endpoint is idempotent.

DELETE

/api/v1/emails/{email}

Delete Email

Soft-deletes an email and emits an email.deleted webhook event.

Requires API key with `write` permission.

Field	Type	Required	Description
email	integer	Yes	Email record ID (route parameter `{email}`).

Request Example

curl -X DELETE "{{ url('/api/v1/emails/123') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "status": "success"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - API key lacks write permission.
HTTP 404 - Email not found in your tenant scope.

Notes

Record is soft deleted, not permanently removed.

GET

/api/v1/emails/{email}/attachments/{attachment}

Attachment URL

Returns a temporary signed attachment download URL.

Requires API key with `read` permission.

Field	Type	Required	Description
email	integer	Yes	Email record ID (route parameter `{email}`).
attachment	integer	Yes	Attachment record ID (route parameter `{attachment}`).

Request Example

curl "{{ url('/api/v1/emails/123/attachments/456') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "data": {
        "url": "https://signed-url",
        "expires_at": "2026-04-28T10:10:00Z"
    }
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 404 - Email or attachment not found in your tenant scope.

Notes

URL expires shortly after issuance.

POST

/api/v1/webhooks

Register Webhook

Creates a tenant-scoped webhook target for email events.

Requires API key with `webhook` permission.

Field	Type	Required	Description
url	url	Yes	Destination webhook URL.
events	array	Yes	Allowed: email.received, email.read, email.deleted, sequencer.email.sent, sequencer.email.opened, sequencer.email.clicked, sequencer.lead.replied, sequencer.lead.bounced, sequencer.lead.unsubscribed, sequencer.campaign.completed.

Request Example

curl -X POST "{{ url('/api/v1/webhooks') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" -H "Content-Type: application/json" -d '{"url":"https://example.com/hook","events":["email.received"]}'

Success Response

{
    "data": {
        "id": 1
    }
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - API key lacks webhook permission.
HTTP 422 - Invalid URL or event selection.

Notes

Deliveries are queued and signed using the webhook secret and timestamp headers.

GET

/api/v1/webhooks

List Webhooks

Returns tenant-scoped webhook endpoints.

Requires API key with `webhook` permission.

Field	Type	Required	Description

Request Example

curl "{{ url('/api/v1/webhooks') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "data": [
        {
            "id": 1,
            "url": "https://example.com/hook",
            "events": [
                "email.received"
            ],
            "is_active": true
        }
    ]
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - API key lacks webhook permission.

Notes

Each row includes `last_triggered_at` when the webhook has fired.

PATCH

/api/v1/webhooks/{webhook}

Update Webhook

Updates URL, events, or active state.

Requires API key with `webhook` permission.

Field	Type	Required	Description
webhook	integer	Yes	Webhook ID (route parameter `{webhook}`).
url	url	No	Destination webhook URL.
events	array	No	Allowed: email.received, email.read, email.deleted, sequencer.email.sent, sequencer.email.opened, sequencer.email.clicked, sequencer.lead.replied, sequencer.lead.bounced, sequencer.lead.unsubscribed, sequencer.campaign.completed.
is_active	boolean	No	Whether webhook should receive deliveries.

Request Example

curl -X PATCH "{{ url('/api/v1/webhooks/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" -H "Content-Type: application/json" -d '{"is_active":false}'

Success Response

{
    "status": "success"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - API key lacks webhook permission.
HTTP 404 - Webhook not found in your tenant scope.
HTTP 422 - Invalid URL or event selection.

Notes

Include at least one of `url`, `events`, or `is_active`.

DELETE

/api/v1/webhooks/{webhook}

Delete Webhook

Deletes a tenant webhook endpoint.

Requires API key with `webhook` permission.

Field	Type	Required	Description
webhook	integer	Yes	Webhook ID (route parameter `{webhook}`).

Request Example

curl -X DELETE "{{ url('/api/v1/webhooks/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "status": "success"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - API key lacks webhook permission.
HTTP 404 - Webhook not found in your tenant scope.

Notes

Permanent delete; queued delivery rows for this webhook are removed.

GET

/api/v1/sequencer/campaigns

List Sequencer Campaigns

Returns paginated campaigns for the tenant.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
status	string	No	Filter by status (draft, active, paused).
q	string	No	Search campaign name.

Request Example

curl -X GET "{{ url('/api/v1/sequencer/campaigns') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "data": []
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

POST

/api/v1/sequencer/campaigns

Create Campaign

Creates a draft campaign. Omitting sequence_id auto-provisions a linked sequence with default schedule.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
name	string	Yes	Campaign name.
sequence_id	integer	No	Existing sequence ID. Omitted values auto-provision a new sequence.
lead_list_id	integer	No	Optional default lead list.
mailbox_ids	array	No	Sender mailbox IDs for rotation. Required before enroll.
settings	object	No	daily_send_limit, ramp_up_percent_per_day, ramp_up_mode (percent\|count), track_opens, track_clicks, schedule_mode (now\|future).
sending_window	object	No	days[], start_hour, start_minute, end_hour, end_minute.
sending_timezone	string	No	IANA timezone (default UTC).

Request Example

curl -X POST "{{ url('/api/v1/sequencer/campaigns') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" -H "Content-Type: application/json" -d '{}'

Success Response

{
    "status": "created"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

Auto-provisioned campaigns include a default Mon–Fri 08:00–18:00 UTC sending window.
Assign mailbox_ids before calling enroll.

GET

/api/v1/sequencer/campaigns/{campaign}

Show Campaign

Returns campaign details with sequence and mailboxes.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
campaign	integer	Yes	Campaign ID.

Request Example

curl -X GET "{{ url('/api/v1/sequencer/campaigns/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "data": []
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

PATCH

/api/v1/sequencer/campaigns/{campaign}

Update Campaign

Updates campaign settings, schedule, mailboxes, or activates a draft campaign.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
campaign	integer	Yes	Campaign ID.
name	string	No	Campaign name.
status	string	No	Set to active on draft campaigns to launch (runs readiness checks).
mailbox_ids	array	No	Mailbox IDs for sender rotation. Active campaigns may add mailboxes but cannot drop existing ones (pause first).
settings	object	No	daily_send_limit, ramp_up_percent_per_day, ramp_up_mode (percent\|count), track_opens, track_clicks, schedule_mode.
sending_window	object	No	Active days and hours for sending.
sending_timezone	string	No	IANA timezone.

Request Example

curl -X PATCH "{{ url('/api/v1/sequencer/campaigns/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" -H "Content-Type: application/json" -d '{}'

Success Response

{
    "status": "updated"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

Activation from draft requires email steps, mailboxes, daily_send_limit > 0, enrolled leads, and a valid sending_window.
Active campaigns cannot remove sender mailboxes via mailbox_ids; pause the campaign first.
HTTP 422 responses include failures[] with human-readable reasons.

DELETE

/api/v1/sequencer/campaigns/{campaign}

Delete Campaign

Deletes a campaign.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
campaign	integer	Yes	Campaign ID.

Request Example

curl -X DELETE "{{ url('/api/v1/sequencer/campaigns/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "status": "deleted"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

POST

/api/v1/sequencer/campaigns/{campaign}/enroll

Enroll Leads in Campaign

Enrolls lead IDs or an entire lead list into a campaign.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
campaign	integer	Yes	Campaign ID.
lead_ids	array	No	Lead IDs to enroll.
lead_list_id	integer	No	Lead list ID to bulk enroll.

Request Example

curl -X POST "{{ url('/api/v1/sequencer/campaigns/1/enroll') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" -H "Content-Type: application/json" -d '{}'

Success Response

{
    "status": "completed",
    "enrolled": 2,
    "skipped": 0
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

Returns HTTP 422 when the campaign has no mailboxes configured.
Provide lead_ids or lead_list_id (not both required, but at least one).

POST

/api/v1/sequencer/campaigns/{campaign}/pause

Pause Campaign

Pauses an active campaign.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
campaign	integer	Yes	Campaign ID.

Request Example

curl -X POST "{{ url('/api/v1/sequencer/campaigns/1/pause') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" -H "Content-Type: application/json" -d '{}'

Success Response

{
    "status": "updated"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

POST

/api/v1/sequencer/campaigns/{campaign}/resume

Resume Campaign

Resumes a paused campaign. Runs the same readiness checks as draft activation (email steps, mailboxes, daily limit, leads, schedule).

Requires API key with `sequencer` permission.

Field	Type	Required	Description
campaign	integer	Yes	Campaign ID.

Request Example

curl -X POST "{{ url('/api/v1/sequencer/campaigns/1/resume') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" -H "Content-Type: application/json" -d '{}'

Success Response

{
    "status": "updated"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

HTTP 422 when readiness checks fail; response includes reason and failures[].

GET

/api/v1/sequencer/campaigns/{campaign}/analytics

Campaign Analytics

Returns funnel metrics, engagement rates, and breakdowns by mailbox, step, and domain.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
campaign	integer	Yes	Campaign ID.

Request Example

curl -X GET "{{ url('/api/v1/sequencer/campaigns/1/analytics') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "data": {
        "campaign_id": 1,
        "funnel": {
            "total_enrolled": 100,
            "sent": 80,
            "opened": 40,
            "clicked": 12,
            "replied": 5,
            "bounced": 2
        },
        "rates": {
            "open_rate": 50,
            "click_rate": 15,
            "reply_rate": 6.25,
            "bounce_rate": 2.5
        },
        "by_mailbox": [],
        "by_step": [],
        "by_domain": []
    }
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

GET

/api/v1/sequencer/sequences

List Sequences

Returns paginated email sequences for the tenant.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
q	string	No	Search sequence name.

Request Example

curl -X GET "{{ url('/api/v1/sequencer/sequences') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "data": []
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

POST

/api/v1/sequencer/sequences

Create Sequence

Creates a sequence with optional initial steps.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
name	string	Yes	Sequence name.
steps	array	No	Initial step definitions.

Request Example

curl -X POST "{{ url('/api/v1/sequencer/sequences') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" -H "Content-Type: application/json" -d '{}'

Success Response

{
    "status": "created"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

GET

/api/v1/sequencer/sequences/{sequence}

Show Sequence

Returns a sequence with steps.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
sequence	integer	Yes	Sequence ID.

Request Example

curl -X GET "{{ url('/api/v1/sequencer/sequences/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "data": []
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

PATCH

/api/v1/sequencer/sequences/{sequence}

Update Sequence

Updates sequence metadata and optional steps.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
sequence	integer	Yes	Sequence ID.
name	string	No	Sequence name.

Request Example

curl -X PATCH "{{ url('/api/v1/sequencer/sequences/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" -H "Content-Type: application/json" -d '{}'

Success Response

{
    "status": "updated"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

PUT

/api/v1/sequencer/sequences/{sequence}/steps

Sync Sequence Steps

Replaces sequence steps in one request.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
sequence	integer	Yes	Sequence ID.
steps	array	Yes	Ordered step payloads.

Request Example

curl -X PUT "{{ url('/api/v1/sequencer/sequences/1/steps') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" -H "Content-Type: application/json" -d '{}'

Success Response

{
    "status": "updated"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

DELETE

/api/v1/sequencer/sequences/{sequence}/steps/{step}

Delete Sequence Step

Deletes a single sequence step.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
sequence	integer	Yes	Sequence ID.
step	integer	Yes	Sequence step ID.

Request Example

curl -X DELETE "{{ url('/api/v1/sequencer/sequences/1/steps/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "status": "deleted"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

DELETE

/api/v1/sequencer/sequences/{sequence}

Delete Sequence

Deletes a sequence.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
sequence	integer	Yes	Sequence ID.

Request Example

curl -X DELETE "{{ url('/api/v1/sequencer/sequences/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "status": "deleted"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

GET

/api/v1/sequencer/leads

List Sequencer Leads

Returns tenant-scoped leads with cursor pagination.

Requires API key with `sequencer` permission and sequencer_enabled plan feature.

Field	Type	Required	Description
status	string	No	Filter by lead status.
list_id	integer	No	Filter by lead list ID.
tag	string	No	Filter by tag name.
saved_filter_id	integer	No	Apply a saved filter.
q	string	No	Search email, name, or company.
cursor	string	No	Cursor for pagination.

Request Example

curl -X GET "{{ url('/api/v1/sequencer/leads') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "data": []
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

POST

/api/v1/sequencer/leads

Create Sequencer Lead

Creates or updates a lead by email address.

Requires API key with `sequencer` permission and sequencer_enabled plan feature.

Field	Type	Required	Description
email	string	Yes	Lead email address.
first_name	string	No	First name. Nullable.
last_name	string	No	Last name. Nullable.
company	string	No	Company name. Nullable.
title	string	No	Job title. Nullable.
job_level	string	No	Job level (e.g. manager, vp). Nullable.
department	string	No	Department. Nullable.
experience	string	No	Experience range (e.g. 5-10 years). Nullable.
person_address	string	No	Person street address. Nullable.
person_city	string	No	Person city. Nullable.
person_state	string	No	Person state/region. Nullable.
person_country	string	No	Person country. Nullable.
phone	string	No	Phone number. Nullable.
linkedin_url	string	No	Person LinkedIn URL. Nullable.
website	string	No	Website URL. Nullable.
company_domain	string	No	Company domain. Nullable.
industry	string	No	Industry. Nullable.
employee_count	string	No	Employee count or range (e.g. 51-200). Nullable.
annual_revenue	string	No	Annual revenue or range (e.g. $10M-$50M). Nullable.
company_linkedin_url	string	No	Company LinkedIn URL. Nullable.
company_address	string	No	Company street address. Nullable.
company_city	string	No	Company city. Nullable.
company_state	string	No	Company state/region. Nullable.
company_country	string	No	Company country. Nullable.
technologies	array	No	List of technology strings. Nullable.
email_provider	string	No	Email provider (e.g. google, microsoft). Nullable.
timezone	string	No	IANA timezone. Nullable.
source	string	No	Lead source. Nullable; defaults to api when omitted.
last_updated	string	No	Enrichment freshness timestamp (parseable datetime). Nullable.
lead_score	integer	No	Lead score (unsigned integer). Nullable.
custom_fields	object	No	Arbitrary key/value bag for non-standard fields. Nullable.

Request Example

curl -X POST "{{ url('/api/v1/sequencer/leads') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" -H "Content-Type: application/json" -d '{}'

Success Response

{
    "status": "created",
    "data": {
        "email": "lead@example.com"
    }
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

POST

/api/v1/sequencer/leads/import

Import Sequencer Leads

Bulk import leads via multipart file, raw CSV string, or leads[] array. ≤50 rows sync (201); >50 rows queued ApiTask (202).

Requires API key with `sequencer` permission and sequencer_enabled plan feature.

Field	Type	Required	Description
file	file	No	Multipart upload field. Accepts csv, txt, xlsx, xls. Max 10 MB. Use multipart/form-data (omit Content-Type: application/json).
csv	string	No	Raw CSV string in JSON body. Max 10 KB. First row must be headers including email.
leads	array	No	Lead objects (max 1000). Each row requires email; optional first_name, last_name, company, title, phone, and other lead fields.
defaults.source	string	No	Optional default source applied to imported rows.

Request Example

curl -X POST "{{ url('/api/v1/sequencer/leads/import') }}" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" \
  -F "file=@/path/to/folder/leads.csv"

Success Response

{
    "status": "completed",
    "mode": "sync",
    "created": 1
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

Provide one of file, csv, or leads.
CSV/spreadsheet: first row is headers (case-insensitive); email column required. Unknown columns go into custom_fields.
Recognized columns include first_name, last_name, company, title, phone, linkedin_url, website, company_domain, industry, timezone, source, lead_score.
Async imports return task_id; poll GET /api/v1/sequencer/leads/import/{task}.

GET

/api/v1/sequencer/leads/import/{task}

Import Task Status

Poll async lead import task progress.

Requires API key with `sequencer` permission and sequencer_enabled plan feature.

Field	Type	Required	Description
task	integer	Yes	ApiTask ID from async import.

Request Example

curl -X GET "{{ url('/api/v1/sequencer/leads/import/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "data": []
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

GET

/api/v1/sequencer/leads/{lead}

Show Sequencer Lead

Returns a single lead with tags and metadata.

Requires API key with `sequencer` permission and sequencer_enabled plan feature.

Field	Type	Required	Description
lead	integer	Yes	Lead ID.

Request Example

curl -X GET "{{ url('/api/v1/sequencer/leads/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "data": []
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

PATCH

/api/v1/sequencer/leads/{lead}

Update Sequencer Lead

Updates lead profile fields and status.

Requires API key with `sequencer` permission and sequencer_enabled plan feature.

Field	Type	Required	Description
lead	integer	Yes	Lead ID.
first_name	string	No	First name.
status	string	No	Lead status enum value.

Request Example

curl -X PATCH "{{ url('/api/v1/sequencer/leads/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" -H "Content-Type: application/json" -d '{}'

Success Response

{
    "status": "updated"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

DELETE

/api/v1/sequencer/leads/{lead}

Delete Sequencer Lead

Deletes a lead from the tenant workspace.

Requires API key with `sequencer` permission and sequencer_enabled plan feature.

Field	Type	Required	Description
lead	integer	Yes	Lead ID.

Request Example

curl -X DELETE "{{ url('/api/v1/sequencer/leads/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "status": "deleted"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

GET

/api/v1/sequencer/lead-tags

List Lead Tags

Returns paginated Lead Tags for the tenant.

Requires API key with `sequencer` permission.

Field	Type	Required	Description

Request Example

curl -X GET "{{ url('/api/v1/sequencer/lead-tags') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "data": []
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

POST

/api/v1/sequencer/lead-tags

Create Lead Tag

Creates a Lead Tag.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
name	string	Yes	Tag name.
color	string	No	Hex color.

Request Example

curl -X POST "{{ url('/api/v1/sequencer/lead-tags') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" -H "Content-Type: application/json" -d '{}'

Success Response

{
    "status": "created"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

GET

/api/v1/sequencer/lead-tags/{leadTag}

Show Lead Tag

Returns a single Lead Tag.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
leadTag	integer	Yes	Lead Tag ID.

Request Example

curl -X GET "{{ url('/api/v1/sequencer/lead-tags/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "data": []
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

PATCH

/api/v1/sequencer/lead-tags/{leadTag}

Update Lead Tag

Updates a Lead Tag.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
leadTag	integer	Yes	Lead Tag ID.

Request Example

curl -X PATCH "{{ url('/api/v1/sequencer/lead-tags/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" -H "Content-Type: application/json" -d '{}'

Success Response

{
    "status": "updated"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

DELETE

/api/v1/sequencer/lead-tags/{leadTag}

Delete Lead Tag

Deletes a Lead Tag.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
leadTag	integer	Yes	Lead Tag ID.

Request Example

curl -X DELETE "{{ url('/api/v1/sequencer/lead-tags/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "status": "deleted"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

GET

/api/v1/sequencer/lead-lists

List Lead Lists

Returns paginated Lead Lists for the tenant.

Requires API key with `sequencer` permission.

Field	Type	Required	Description

Request Example

curl -X GET "{{ url('/api/v1/sequencer/lead-lists') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "data": []
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

POST

/api/v1/sequencer/lead-lists

Create Lead List

Creates a Lead List.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
name	string	Yes	List name.
description	string	No	Optional description.
lead_ids	array	No	Initial member lead IDs.

Request Example

curl -X POST "{{ url('/api/v1/sequencer/lead-lists') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" -H "Content-Type: application/json" -d '{}'

Success Response

{
    "status": "created"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

GET

/api/v1/sequencer/lead-lists/{leadList}

Show Lead List

Returns a single Lead List.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
leadList	integer	Yes	Lead List ID.

Request Example

curl -X GET "{{ url('/api/v1/sequencer/lead-lists/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "data": []
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

PATCH

/api/v1/sequencer/lead-lists/{leadList}

Update Lead List

Updates a Lead List.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
leadList	integer	Yes	Lead List ID.

Request Example

curl -X PATCH "{{ url('/api/v1/sequencer/lead-lists/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" -H "Content-Type: application/json" -d '{}'

Success Response

{
    "status": "updated"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

DELETE

/api/v1/sequencer/lead-lists/{leadList}

Delete Lead List

Deletes a Lead List.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
leadList	integer	Yes	Lead List ID.

Request Example

curl -X DELETE "{{ url('/api/v1/sequencer/lead-lists/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "status": "deleted"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

GET

/api/v1/sequencer/lead-notes

List Lead Notes

Returns paginated Lead Notes for the tenant.

Requires API key with `sequencer` permission.

Field	Type	Required	Description

Request Example

curl -X GET "{{ url('/api/v1/sequencer/lead-notes') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "data": []
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

POST

/api/v1/sequencer/lead-notes

Create Lead Note

Creates a Lead Note.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
lead_id	integer	Yes	Lead ID.
body	string	Yes	Note body.

Request Example

curl -X POST "{{ url('/api/v1/sequencer/lead-notes') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" -H "Content-Type: application/json" -d '{}'

Success Response

{
    "status": "created"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

GET

/api/v1/sequencer/lead-notes/{leadNote}

Show Lead Note

Returns a single Lead Note.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
leadNote	integer	Yes	Lead Note ID.

Request Example

curl -X GET "{{ url('/api/v1/sequencer/lead-notes/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "data": []
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

PATCH

/api/v1/sequencer/lead-notes/{leadNote}

Update Lead Note

Updates a Lead Note.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
leadNote	integer	Yes	Lead Note ID.

Request Example

curl -X PATCH "{{ url('/api/v1/sequencer/lead-notes/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" -H "Content-Type: application/json" -d '{}'

Success Response

{
    "status": "updated"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

DELETE

/api/v1/sequencer/lead-notes/{leadNote}

Delete Lead Note

Deletes a Lead Note.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
leadNote	integer	Yes	Lead Note ID.

Request Example

curl -X DELETE "{{ url('/api/v1/sequencer/lead-notes/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "status": "deleted"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

GET

/api/v1/sequencer/saved-filters

List Saved Filters

Returns paginated Saved Filters for the tenant.

Requires API key with `sequencer` permission.

Field	Type	Required	Description

Request Example

curl -X GET "{{ url('/api/v1/sequencer/saved-filters') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "data": []
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

POST

/api/v1/sequencer/saved-filters

Create Saved Filter

Creates a Saved Filter.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
name	string	Yes	Filter name.
filters	object	Yes	Filter criteria (status, q, tag, list_id).

Request Example

curl -X POST "{{ url('/api/v1/sequencer/saved-filters') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" -H "Content-Type: application/json" -d '{}'

Success Response

{
    "status": "created"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

GET

/api/v1/sequencer/saved-filters/{savedFilter}

Show Saved Filter

Returns a single Saved Filter.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
savedFilter	integer	Yes	Saved Filter ID.

Request Example

curl -X GET "{{ url('/api/v1/sequencer/saved-filters/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "data": []
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

PATCH

/api/v1/sequencer/saved-filters/{savedFilter}

Update Saved Filter

Updates a Saved Filter.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
savedFilter	integer	Yes	Saved Filter ID.

Request Example

curl -X PATCH "{{ url('/api/v1/sequencer/saved-filters/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" -H "Content-Type: application/json" -d '{}'

Success Response

{
    "status": "updated"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

DELETE

/api/v1/sequencer/saved-filters/{savedFilter}

Delete Saved Filter

Deletes a Saved Filter.

Requires API key with `sequencer` permission.

Field	Type	Required	Description
savedFilter	integer	Yes	Saved Filter ID.

Request Example

curl -X DELETE "{{ url('/api/v1/sequencer/saved-filters/1') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "status": "deleted"
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

POST

/api/v1/sequencer/leads/webhook

Webhook Create Lead

Creates a lead from an inbound webhook payload.

Requires API key with `sequencer` permission and sequencer_enabled plan feature.

Field	Type	Required	Description
email	string	Yes	Lead email address.
list_id	integer	No	Optional lead list to attach.

Request Example

curl -X POST "{{ url('/api/v1/sequencer/leads/webhook') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" -H "Content-Type: application/json" -d '{}'

Success Response

{
    "data": []
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
HTTP 404 - Resource not found in tenant scope.
HTTP 422 - Validation error.

Notes

POST

/api/v1/transactional/send

Send Transactional Email

Queues a transactional email from a dashboard-saved message template. Subject and HTML come from the template after `{{token}}` substitution. Recipients are not stored as contacts.

Requires API key with `transactional` permission and plan feature `transactional_enabled`.

Field	Type	Required	Description
transactional_message_id	integer	Yes	Tenant template ID. Must be enabled and have a saved subject plus HTML.
to	object	Yes	`email` (required), `name` (optional).
from	object	Yes	`email` must match a tenant mailbox (case-insensitive). `name` optional; defaults to mailbox display name.
variables	object	No	Key/value map for `{{token}}` substitution in the saved template.
reply_to	string	No	Optional reply-to address.
headers	object	No	Custom headers. Only names starting with `X-` / `x-` are stored; others are dropped.
idempotency_key	string	No	Client-chosen unique key per logical send (max 191), e.g. order id or UUID. Same tenant + key + same payload replays the original send. Same key with a different payload returns HTTP 409. Omit to always create a new outbound. Never use a human description.
attachments	array	No	Optional base64 attachments (`filename`, `content_type`, `content`). Count/size/MIME limits in `config/transactional.php`.

Request Example

curl --fail-with-body --silent --show-error \
  -X POST "{{ url('/api/v1/transactional/send') }}" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional_message_id": 1,
    "to": { "email": "user@example.com", "name": "Ada" },
    "from": { "email": "noreply@yourdomain.com" },
    "variables": { "first_name": "Ada" },
    "idempotency_key": "order-42-welcome"
  }'

Success Response

{
    "status": "success",
    "data": {
        "id": 101,
        "transactional_message_id": 1,
        "status": "queued",
        "channel": "transactional",
        "from_address": "noreply@yourdomain.com",
        "from_name": "Acme",
        "to_addresses": [
            "user@example.com"
        ],
        "subject": "Hello Ada",
        "message_id": null,
        "idempotency_key": "order-42-welcome",
        "failure_reason": null,
        "queued_at": "2026-09-04T12:00:00.000000Z",
        "sent_at": null,
        "delivered_at": null,
        "last_deferred_at": null,
        "created_at": "2026-09-04T12:00:00.000000Z",
        "delivery_events": []
    },
    "idempotent_replay": false
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - Your current plan does not include Transactional Email.
HTTP 403 - API key does not have transactional permission.
HTTP 409 - This idempotency_key was already used for a different send. Use a unique key per logical send, or omit idempotency_key.
HTTP 422 - Do not send subject; it is taken from the saved message template.
HTTP 422 - This message has no saved template.
HTTP 422 - The from email must belong to one of your mailboxes.

Notes

HTTP 202 on a new queue; HTTP 200 when `idempotency_key` replays an existing matching send (job is not dispatched again); HTTP 409 when the key was used for a different payload.
`status` is queue/SMTP acceptance; inbox confirmation is `delivered_at` / `delivery_events`.
Do not send `subject`, `message`, or `text`; they are prohibited. Design the template under Transactional → Email Templates.
No List-Unsubscribe headers are injected for transactional sends.
Open/click tracking follows the template `track_opens` / `track_clicks` flags.
Throttled at 60 requests/min per API key (`api-v1-transactional`).

GET

/api/v1/transactional/messages

List Transactional Messages

Lists transactional templates for the authenticated tenant (enabled and disabled). Bodies are not included.

Requires API key with `transactional` permission and plan feature `transactional_enabled`.

Field	Type	Required	Description
per_page	integer	No	Page size (1–100, default 50).

Request Example

curl "{{ url('/api/v1/transactional/messages') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "data": [
        {
            "id": 1,
            "name": "Password Reset",
            "slug": null,
            "description": null,
            "subject": "Reset your password",
            "enabled": true,
            "required_variables": [],
            "track_opens": true,
            "track_clicks": true,
            "source": "manual"
        }
    ]
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - API key does not have transactional permission.
HTTP 403 - Your current plan does not include Transactional Email.

Notes

Create and edit templates in the dashboard under Transactional → Email Templates. There is no REST create/update for templates.
Response is a Laravel paginated resource (`data`, `links`, `meta`), not `{status: success}`.
`slug` is nullable; send/list identify templates by `id`.
Dashboard-created rows use `source` `manual`. HTML and plaintext are omitted from this list.
MCP `list_transactional_messages` returns enabled templates only; this REST list includes disabled rows.

GET

/api/v1/transactional/sends/{outboundEmail}

Get Transactional Send

Shows a single transactional outbound send for the tenant.

Requires API key with `transactional` permission and plan feature `transactional_enabled`.

Field	Type	Required	Description
outboundEmail	integer	Yes	Outbound email ID.

Request Example

curl "{{ url('/api/v1/transactional/sends/101') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"

Success Response

{
    "status": "success",
    "data": {
        "id": 101,
        "transactional_message_id": 1,
        "status": "sent",
        "channel": "transactional",
        "from_address": "noreply@yourdomain.com",
        "from_name": "Acme",
        "to_addresses": [
            "user@example.com"
        ],
        "subject": "Hello Ada",
        "message_id": "<abc@mail.example>",
        "idempotency_key": "order-42-welcome",
        "failure_reason": null,
        "queued_at": "2026-09-04T12:00:00.000000Z",
        "sent_at": "2026-09-04T12:00:03.000000Z",
        "delivered_at": "2026-09-04T12:00:05.000000Z",
        "last_deferred_at": null,
        "created_at": "2026-09-04T12:00:00.000000Z",
        "delivery_events": [
            {
                "event_type": "delivered",
                "provider": "mailcow",
                "occurred_at": "2026-09-04T12:00:05.000000Z",
                "diagnostic": null
            }
        ]
    }
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - API key does not have transactional permission.
HTTP 404 - Send not found in your tenant scope or not transactional.

Notes

Non-transactional outbound rows (compose, sequencer, SMTP gateway) return 404.
`status` is queue/SMTP acceptance; `delivered_at` and `delivery_events` reflect provider delivery webhooks.

POST

/api/v1/transactional/variables

Create or Overwrite Variable

Registers a typed variable in the tenant Variable Manager. Duplicate keys return HTTP 409 unless `overwrite=true`.

Requires API key with `transactional` permission and plan feature `transactional_enabled`.

Field	Type	Required	Description
key	string	Yes	Variable key used in `{{key}}` tokens (letters, numbers, `_`, `.`, `-`; max 64).
data_type	string	Yes	One of: string, integer, date, url, boolean, email, currency.
default_value	string	No	Applied when the send payload omits the variable (max 2000).
overwrite	boolean	No	When true, replaces an existing key instead of returning 409.

Request Example

curl --fail-with-body --silent --show-error \
  -X POST "{{ url('/api/v1/transactional/variables') }}" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "otp",
    "data_type": "integer",
    "overwrite": false
  }'

Success Response

{
    "status": "success",
    "data": {
        "id": 1,
        "key": "otp",
        "data_type": "integer",
        "default_value": null,
        "source": "api"
    },
    "overwritten": false
}

Error Responses

HTTP 401 - Invalid API key.
HTTP 403 - API key does not have transactional permission.
HTTP 403 - Your current plan does not include Transactional Email.
HTTP 409 - A variable with this key already exists. Pass overwrite=true to replace it.
HTTP 422 - The variable key may only contain letters, numbers, underscores, dots, and hyphens.

Notes

HTTP 201 on create; HTTP 200 when overwriting an existing key (`overwritten: true`).
Duplicate keys never silently overwrite without `overwrite=true`.
When any registry rows exist, send rejects unregistered `{{token}}` keys used in the template.