`domain_quota` is a string with a `GB` suffix; `0GB` means unlimited in list responses (non-zero may appear on older rows).
GET
/api/v1/domains/{domain}/records
List DNS Records
Returns every DNS record stored for one domain: the required mail records managed by Mails.now (`origin` = `system`) and your own records (`origin` = `user`), ordered by type then host.
Header auth required: `Authorization: Bearer <key>` or `X-Api-Key` with `read` permission.
Field
Type
Required
Description
domain
string
Yes
Domain or subdomain hostname owned by your account, for example `example.com`.
HTTP 403 - This DNS record is managed by Mails.now and cannot be changed.
HTTP 404 - DNS record not found for this domain.
Notes
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).
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.
{
"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.
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.
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`.
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.
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.
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.
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).
When both are sent, lead_list_id is used. The request example shows both so each shape is visible.
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"
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"
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[].
POST
/api/v1/sequencer/campaigns/{campaign}/complete
Complete Campaign
Marks an active or paused campaign as complete. Stops sending, stops open enrollments, fails queued outbounds, frees sender mailboxes, and deactivates automation rules. Completed campaigns cannot be reopened.
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/complete') }}" -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY"
Success Response
{
"status": "completed",
"message": "Campaign marked complete. Sending has stopped and mailboxes were freed. Completed campaigns cannot be reopened; duplicate this campaign to send again."
}
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
Only the campaign owner or an admin may complete a campaign.
HTTP 422 when the campaign is not active or paused.
Lead lists, sequence, and sent history are preserved.
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"
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?q=intro') }}" -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.
description
string
No
Optional description (max 5000 characters).
steps
array
No
Step definitions. When sent, replaces the existing step list.
steps.*.type
string
Yes
Step type: email, follow_up, wait, or condition. Required for each step.
steps.*.position
integer
Yes
Step order, starting at 1. Required for each step.
steps.*.subject
string
No
Email subject (max 500 characters).
steps.*.body_text
string
No
Plain-text email body.
steps.*.body_html
string
No
HTML email body.
steps.*.delay_minutes
integer
No
Minutes to wait after the previous step.
steps.*.settings
object
No
Step settings. Condition steps use field, operator (equals, not_equals, contains, empty, not_empty, in), and value.
Request Example
curl -X POST "{{ url('/api/v1/sequencer/sequences') }}" \
-H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Q4 Outbound Intro",
"description": "Three-touch intro sequence for marketing leaders.",
"steps": [
{
"type": "email",
"position": 1,
"subject": "Quick question about {{company}}",
"body_text": "Hi {{first_name}},\n\nI noticed {{company}} is growing its marketing team. Would a 15-minute call next week be useful?\n\nBest,\nAlex",
"body_html": "<p>Hi {{first_name}},</p><p>I noticed {{company}} is growing its marketing team. Would a 15-minute call next week be useful?</p><p>Best,<br>Alex</p>",
"delay_minutes": 0
},
{
"type": "condition",
"position": 2,
"delay_minutes": 2880,
"settings": {
"field": "status",
"operator": "not_equals",
"value": "replied"
}
},
{
"type": "follow_up",
"position": 3,
"subject": "Re: Quick question about {{company}}",
"body_text": "Hi {{first_name}},\n\nJust bumping this to the top of your inbox. Happy to share a short case study if helpful.\n\nAlex",
"body_html": "<p>Hi {{first_name}},</p><p>Just bumping this to the top of your inbox. Happy to share a short case study if helpful.</p><p>Alex</p>",
"delay_minutes": 4320
}
]
}'
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
Merge tags such as {{first_name}} and {{company}} are replaced with lead values when emails are sent.
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.
description
string
No
Optional description (max 5000 characters).
steps
array
No
Step definitions. When sent, replaces the existing step list.
steps.*.id
integer
No
Existing step ID to update. Omit to create a new step. Existing steps missing from the list are deleted.
steps.*.type
string
Yes
Step type: email, follow_up, wait, or condition. Required for each step.
steps.*.position
integer
Yes
Step order, starting at 1. Required for each step.
steps.*.subject
string
No
Email subject (max 500 characters).
steps.*.body_text
string
No
Plain-text email body.
steps.*.body_html
string
No
HTML email body.
steps.*.delay_minutes
integer
No
Minutes to wait after the previous step.
steps.*.settings
object
No
Step settings. Condition steps use field, operator (equals, not_equals, contains, empty, not_empty, in), and value.
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 '{
"name": "Q4 Outbound Intro v2",
"description": "Updated copy with a case study follow-up.",
"steps": [
{
"id": 101,
"type": "email",
"position": 1,
"subject": "Quick question about {{company}}",
"body_text": "Hi {{first_name}},\n\nI noticed {{company}} is growing its marketing team. Would a 15-minute call next week be useful?\n\nBest,\nAlex",
"body_html": "<p>Hi {{first_name}},</p><p>I noticed {{company}} is growing its marketing team. Would a 15-minute call next week be useful?</p><p>Best,<br>Alex</p>",
"delay_minutes": 0
},
{
"id": 102,
"type": "condition",
"position": 2,
"delay_minutes": 2880,
"settings": {
"field": "status",
"operator": "not_equals",
"value": "replied"
}
},
{
"type": "follow_up",
"position": 3,
"subject": "Re: Quick question about {{company}}",
"body_text": "Hi {{first_name}},\n\nJust bumping this to the top of your inbox. Happy to share a short case study if helpful.\n\nAlex",
"body_html": "<p>Hi {{first_name}},</p><p>Just bumping this to the top of your inbox. Happy to share a short case study if helpful.</p><p>Alex</p>",
"delay_minutes": 4320
}
]
}'
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
Body fields are optional. Send only the fields you want to change. The request example includes sample values for each accepted field.
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. Replaces all existing steps.
steps.*.id
integer
No
Existing step ID to update. Omit to create a new step. Existing steps missing from the list are deleted.
steps.*.type
string
Yes
Step type: email, follow_up, wait, or condition. Required for each step.
steps.*.position
integer
Yes
Step order, starting at 1. Required for each step.
steps.*.subject
string
No
Email subject (max 500 characters).
steps.*.body_text
string
No
Plain-text email body.
steps.*.body_html
string
No
HTML email body.
steps.*.delay_minutes
integer
No
Minutes to wait after the previous step.
steps.*.settings
object
No
Step settings. Condition steps use field, operator (equals, not_equals, contains, empty, not_empty, in), and value.
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 '{
"steps": [
{
"id": 101,
"type": "email",
"position": 1,
"subject": "Quick question about {{company}}",
"body_text": "Hi {{first_name}},\n\nI noticed {{company}} is growing its marketing team. Would a 15-minute call next week be useful?\n\nBest,\nAlex",
"body_html": "<p>Hi {{first_name}},</p><p>I noticed {{company}} is growing its marketing team. Would a 15-minute call next week be useful?</p><p>Best,<br>Alex</p>",
"delay_minutes": 0
},
{
"id": 102,
"type": "condition",
"position": 2,
"delay_minutes": 2880,
"settings": {
"field": "status",
"operator": "not_equals",
"value": "replied"
}
},
{
"type": "follow_up",
"position": 3,
"subject": "Re: Quick question about {{company}}",
"body_text": "Hi {{first_name}},\n\nJust bumping this to the top of your inbox. Happy to share a short case study if helpful.\n\nAlex",
"body_html": "<p>Hi {{first_name}},</p><p>Just bumping this to the top of your inbox. Happy to share a short case study if helpful.</p><p>Alex</p>",
"delay_minutes": 4320
}
]
}'
Success Response
{
"status": "updated"
}
Error Responses
HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
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
lead_id
integer
No
Filter notes by lead ID.
Request Example
curl -X GET "{{ url('/api/v1/sequencer/lead-notes?lead_id=501') }}" -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 '{
"lead_id": 501,
"body": "Spoke with Jane on the phone. Interested in the enterprise plan; follow up after their Q4 budget review."
}'
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.
body
string
Yes
Note body (max 5000 characters).
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 '{
"body": "Budget approved. Demo booked for next Tuesday at 10:00 CT."
}'
Success Response
{
"status": "updated"
}
Error Responses
HTTP 401 - Invalid API key.
HTTP 403 - Plan does not include Email Sequencer or key lacks permission.
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`.
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`.