{ "openapi": "3.1.0", "info": { "title": "Mails.now API", "version": "1.0.0", "description": "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)." }, "servers": [ { "url": "https://mails.now/api" } ], "paths": { "/v1/create/domain": { "post": { "summary": "Create Domain", "description": "Creates a new base domain in your Mails.now workspace and queues provisioning in the background.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\nInvalid hostnames return HTTP 422 before enqueue; duplicates return HTTP 409.\n\nPoll `GET /api/v1/get/domain?task_id=…`. When `completed`, `results` includes DNS `records` (MX/TXT/A).\n\nRemote mail server defaults apply on provision; quota fields are not accepted on this request.", "tags": [ "Domains" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" }, "example": { "status": "success", "domain": "example.com", "task_id": 101 } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "An active pricing plan is required before you can create domains, subdomains, or mailboxes via the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "This domain is already registered on Mails.now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "First validation error message (invalid body fields).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "Domain": { "type": "string", "description": "Fully qualified hostname (e.g. example.com). Omit http(s)://; single-label names are rejected (same rules as the dashboard Add domain form)." }, "Params": { "type": "object", "description": "Optional keys (for example `total_mailbox_allowed`)." } }, "required": [ "Domain" ] } } } } } }, "/v1/get/domain": { "get": { "summary": "Get Domain Task", "description": "Polls a root domain create task created by `POST /api/v1/create/domain`.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\n`status` may be `queued`, `running`, `completed`, or `failed`. Only `failed` returns HTTP 422 with `reason` from the task.\n\nWhile `queued` or `running`, `results` is often an empty array until the job finishes.\n\nResponses include `Task_id` (integer) and `task_id` (same value as a string).", "tags": [ "Domains" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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": "", "priority": "—", "status": "Not checked" } ] }, "status": "completed", "task_id": "101" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Task ID was not found for this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Task type does not match this endpoint. Dynamic failure message from the queue job (same shape as other errors).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "task_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Task identifier returned by Create Domain." } ] } }, "/v1/create/sub-domain": { "post": { "summary": "Create Sub-Domain Batch", "description": "Creates up to 10 sub-domains under an existing parent domain in a single queued task.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\nAfter a successful run: at most one request per 2 minutes per API key and parent domain.\n\nPoll `GET /api/v1/get/sub-domain?task_id=…`. When `completed`, nested `results` are keyed by FQDN.\n\nProvisioning uses the same remote defaults as Create Domain; quota fields are not accepted.", "tags": [ "Domains" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" }, "example": { "status": "success", "domain": "example.com", "task_id": 202 } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "An active pricing plan is required before you can create domains, subdomains, or mailboxes via the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Parent domain was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Params.sub_domains must be a non-empty array (or validation on labels). Maximum 10 sub-domains are allowed per request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Sub-domain requests are limited to once per 2 minutes for this domain and API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "Domain": { "type": "string", "description": "Existing parent (root) domain owned by your account. Must be a valid dotted hostname (same rules as Create Domain / dashboard)." } }, "required": [ "Domain" ] } } } } } }, "/v1/get/sub-domain": { "get": { "summary": "Get Sub-Domain Task", "description": "Polls a sub-domain batch task from `POST /api/v1/create/sub-domain`.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\n`status` values are the same as other task endpoints (`queued`, `running`, `completed`, `failed`).\n\nResponses include `Task_id` (integer) and `task_id` (same value as a string).", "tags": [ "Domains" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Task ID was not found for this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Task type does not match this endpoint. Dynamic failure message from provisioning.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "task_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Task identifier returned by Create Sub-Domain." } ] } }, "/v1/list/domain": { "get": { "summary": "List Domains", "description": "Returns all domains for the API key owner account, keyed by domain name.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\n`domain_type` is `root` or `sub`.\n\n`domain_quota` is a string with a `GB` suffix; `0GB` means unlimited in list responses (non-zero may appear on older rows).", "tags": [ "Domains" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ] } }, "/v1/delete/domain/bulk": { "post": { "summary": "Bulk Delete Domains", "description": "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.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key` with `write` permission.\n\nCooldown: 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.\n\nPoll `GET /api/v1/get/delete/domain/bulk?task_id=…` until `completed` or `failed`.\n\nWhen `completed`, `results` entries use `deleted`, `failed`, or `skipped` with optional `reason`; partial failures still yield task `completed`.\n\nDeleting a root domain removes descendant hostnames and their mailboxes in dependency order.", "tags": [ "Domains" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" }, "example": { "status": "success", "task_id": 801 } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "An active pricing plan is required before you can create, bulk-delete, or manage domains, subdomains, or mailboxes via the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error (empty array, too many domains, invalid hostname, or duplicate entries).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests (bulk domain delete is limited to one successfully enqueued call per 5 minutes per API key and IP).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "Domains": { "type": "array", "items": { "type": "string" }, "description": "Fully qualified hostnames to remove (1–10 per request). Duplicates are rejected. Same hostname rules as create domain (no scheme; valid dotted hostname)." } }, "required": [ "Domains" ] } } } } } }, "/v1/get/delete/domain/bulk": { "get": { "summary": "Get Bulk Delete Domains Task", "description": "Polls a bulk domain delete task created by `POST /api/v1/delete/domain/bulk`.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key` with `read` permission.\n\n`status` may be `queued`, `running`, `completed`, or `failed`. Only `failed` (task-level) returns HTTP 422 with `reason` from the task.\n\nPer-domain outcomes (`deleted`, `failed`, or `skipped`) appear inside `results` while the overall task can still be `completed`.", "tags": [ "Domains" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Task ID was not found for this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Task type does not match this endpoint. Dynamic failure message from `error_message` when the task fails.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "task_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Task identifier returned by Bulk Delete Domains." } ] } }, "/v1/create/mailbox/single": { "post": { "summary": "Create Single Mailbox", "description": "Queues one mailbox creation request for a domain that belongs to your account.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\nInvalid bodies return HTTP 422 before enqueue. Only numeric `0` for `Params.password` triggers auto-generation (string `\"0\"` is rejected).\n\nPoll `GET /api/v1/get/mailbox/single?task_id=…`; remote failures return HTTP 422 on that poll.\n\nCreate and manage send patterns / sender signatures in the dashboard Settings pages. Use List Send Patterns and List Sender Signatures to discover IDs for assignment.", "tags": [ "Mailboxes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" }, "example": { "status": "success", "task_id": 123 } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "An active pricing plan is required before you can create domains, subdomains, or mailboxes via the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Domain not found for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "First validation error message (invalid body fields).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "Email_fullname": { "type": "string", "description": "Display name stored on the mailbox (not the email local-part)." }, "single_bulk": { "type": "string", "description": "Must be `single`." }, "Domain": { "type": "string", "description": "Target domain hostname." }, "Params": { "type": "object", "description": "Payload object for mailbox provisioning details." } }, "required": [ "Email_fullname", "single_bulk", "Domain", "Params" ] } } } } } }, "/v1/create/mailbox/bulk": { "post": { "summary": "Create Bulk Mailboxes", "description": "Queues a bulk mailbox provisioning task and returns a task ID for later retrieval.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\nAfter a successful run: at most one bulk create per 2 minutes per API key and target hostname.\n\n`Params.mailbox_no` must be between 1 and 100.\n\nIf a generated mailbox address already exists, it is skipped and the task continues creating the remaining addresses.\n\nIf all requested addresses already exist, the task still completes successfully with `total_email` set to `0` and an empty `results` object.\n\nOnly numeric `0` for `Params.password` triggers per-mailbox auto-generation (string `\"0\"` is rejected).\n\nPoll `GET /api/v1/get/mailbox/bulk?task_id=…`; remote failures return HTTP 422 on that poll.", "tags": [ "Mailboxes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" }, "example": { "status": "success", "task_id": 456 } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "An active pricing plan is required before you can create domains, subdomains, or mailboxes via the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Domain not found for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "First validation error message (invalid body fields).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Bulk mailbox requests are limited to once per 2 minutes for this domain and API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "Email_fullname": { "type": "string", "description": "Display name used with internal rules to derive unique mailbox local-parts." }, "single_bulk": { "type": "string", "description": "Must be `bulk`." }, "Domain": { "type": "string", "description": "Target domain hostname." }, "Params": { "type": "object", "description": "Payload object for mailbox provisioning details." } }, "required": [ "Email_fullname", "single_bulk", "Domain", "Params" ] } } } } } }, "/v1/get/mailbox/single": { "get": { "summary": "Get Single Mailbox Task", "description": "Fetches status and final result for a single mailbox provisioning task.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\n`status` is `queued`, `running`, `completed`, or `failed`. While pending, `results` is often empty.\n\nBoth `Task_id` (int) and `task_id` (string) are returned with the same value.\n\nWhen `completed`, each entry includes `email`, `password`, `quota`, `domain`, `provisioning`, `create_date`, reputation fields, `send_pattern_id`, and `sender_signature_id` (no per-entry `status`).\n\nIf create used `Params.password: 0`, the response `password` is generated per mailbox.", "tags": [ "Mailboxes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Task ID was not found for this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Task type does not match this endpoint. Dynamic failure message from `error_message` when the task fails.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "task_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Task identifier returned by create endpoint." } ] } }, "/v1/get/mailbox/bulk": { "get": { "summary": "Get Bulk Mailbox Task", "description": "Fetches status and per-mailbox results for a bulk mailbox provisioning task.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\n`status` follows the same lifecycle as single mailbox tasks.\n\nResponses include `Task_id` (integer) and `task_id` (same value as a string).\n\nWhen some requested addresses already exist, those addresses are skipped and `total_email` reflects only newly created mailboxes.\n\nIf all requested addresses already exist, the task still completes successfully with `total_email` set to `0` and an empty `results` object.\n\nResults include mailbox-by-mailbox status details when `completed`.\n\nIf bulk create used numeric `Params.password: 0`, each mailbox result includes its own generated `password` value.", "tags": [ "Mailboxes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Task ID was not found for this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Task type does not match this endpoint. Dynamic failure message from `error_message` when the task fails.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "task_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Task identifier returned by bulk create endpoint." } ] } }, "/v1/delete/mailbox/bulk": { "post": { "summary": "Bulk Delete Mailboxes", "description": "Queues removal of up to 100 mailbox addresses owned by your account. Deletes run sequentially; there is no artificial delay between items.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key` with `write` permission.\n\nCooldown: 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.\n\nPoll `GET /api/v1/get/delete/mailbox/bulk?task_id=…` until `completed` or `failed`.\n\nWhen `completed`, `results` entries use `deleted`, `failed`, or `skipped` with optional `reason`.", "tags": [ "Mailboxes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" }, "example": { "status": "success", "task_id": 802 } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "An active pricing plan is required before you can create, bulk-delete, or manage domains, subdomains, or mailboxes via the API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error (empty array, too many addresses, invalid email, or duplicate entries).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests (bulk mailbox delete is limited to one successfully enqueued call per 5 minutes per API key and IP).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "Mailboxes": { "type": "array", "items": { "type": "string" }, "description": "Full RFC email addresses (1–100 per request). Duplicates are rejected." } }, "required": [ "Mailboxes" ] } } } } } }, "/v1/get/delete/mailbox/bulk": { "get": { "summary": "Get Bulk Delete Mailboxes Task", "description": "Polls a bulk mailbox delete task created by `POST /api/v1/delete/mailbox/bulk`.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key` with `read` permission.\n\n`total_email` mirrors the request size (count of addresses submitted), not the number successfully deleted.\n\nPer-mailbox outcomes (`deleted`, `failed`, or `skipped`) appear inside `results` while the overall task can still be `completed`.", "tags": [ "Mailboxes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Task ID was not found for this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Task type does not match this endpoint. Dynamic failure message from `error_message` when the task fails.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "task_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Task identifier returned by Bulk Delete Mailboxes." } ] } }, "/v1/list/mailbox": { "get": { "summary": "List Mailboxes", "description": "Returns all mailboxes for a specific owned domain, keyed by full email address.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\n`imap_credentials` only when `include_credentials=true`.\n\n`mailbox_quota` is a string with an `MB` suffix; `0MB` means unlimited (non-zero may appear on older rows).\n\nEach mailbox result includes `reputation_level_id`, `level_name`, send limits, `send_pattern_id`, and `sender_signature_id` (nullable).", "tags": [ "Mailboxes" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Domain not found for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Domain to list mailboxes for." }, { "name": "include_credentials", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Include `imap_credentials` in each mailbox result when true." } ] } }, "/v1/list/send-pattern": { "get": { "summary": "List Send Patterns", "description": "Returns send patterns owned by the API key user, including how many mailboxes currently use each pattern.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\nCreate and edit patterns in Settings → Send Pattern. Patterns with `assigned_mailbox_count` > 0 cannot be deleted until mailboxes are reassigned.\n\nUse `id` as `Params.send_pattern_id` when creating mailboxes.", "tags": [ "Mails.now" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ] } }, "/v1/list/sender-signature": { "get": { "summary": "List Sender Signatures", "description": "Returns sender settings (signatures) owned by the API key user, including how many mailboxes currently use each signature.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\nCreate and edit signatures in Settings → Sender Settings. Signatures with `assigned_mailbox_count` > 0 cannot be deleted until mailboxes are reassigned.\n\nUse `id` as `Params.sender_signature_id` when creating mailboxes.", "tags": [ "Mails.now" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ] } }, "/v1/create/alias": { "post": { "summary": "Create Alias", "description": "Queues an alias or forwarder. `goto` can be a local mailbox or external address(es). Use `Params.catch_all=true` for @domain catch-all.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\nPoll `GET /api/v1/get/alias?task_id=` for completion.\n\nExternal destinations are forwarders; local mailbox destinations are aliases.", "tags": [ "Mails.now" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" }, "example": { "status": "success", "task_id": 123 } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Domain not found for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Alias already exists / goto invalid / plan limit reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "Domain": { "type": "string", "description": "Owned domain hostname." } }, "required": [ "Domain" ] } } } } } }, "/v1/create/alias/bulk": { "post": { "summary": "Create Bulk Aliases", "description": "Queues multiple aliases in one task via `Params.aliases`.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\nPoll `GET /api/v1/get/alias?task_id=`.", "tags": [ "Mails.now" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" }, "example": { "status": "success", "task_id": 124 } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation or capacity error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "Domain": { "type": "string", "description": "Owned domain hostname." } }, "required": [ "Domain" ] } } } } } }, "/v1/edit/alias": { "post": { "summary": "Edit Alias", "description": "Queues an update for an existing alias (`goto`, `active`, `sender_allowed`).\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\nPoll `GET /api/v1/get/alias?task_id=`.", "tags": [ "Mails.now" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success", "task_id": 125 } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Alias not found or goto invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "Existing alias address." }, "goto": { "type": "array", "items": { "type": "string" }, "description": "Updated destination(s)." }, "active": { "type": "boolean", "description": "Enable or disable the alias." }, "sender_allowed": { "type": "boolean", "description": "Allow sending as this alias." } }, "required": [ "address" ] } } } } } }, "/v1/get/alias": { "get": { "summary": "Get Alias Task", "description": "Poll create/edit/bulk alias task status.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.", "tags": [ "Mails.now" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "Task_id": 123, "status": "completed", "results": [], "task_id": "123" } } } }, "404": { "description": "Task ID was not found for this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Task type does not match this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "task_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Task id from create/edit endpoints." } ] } }, "/v1/list/alias": { "get": { "summary": "List Aliases", "description": "Lists aliases for an owned domain.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.", "tags": [ "Mails.now" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "domain": "example.com", "results": { "sales@example.com": { "goto": [ "team@example.com" ], "active": true, "is_catch_all": false, "provisioning_status": "active" } }, "status": "success" } } } }, "404": { "description": "Domain not found for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Domain hostname." } ] } }, "/v1/delete/alias/bulk": { "post": { "summary": "Bulk Delete Aliases", "description": "Queues deletion of one or more aliases by address.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.\n\nPoll `GET /api/v1/get/delete/alias/bulk?task_id=`.", "tags": [ "Mails.now" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskResponse" }, "example": { "status": "success", "task_id": 126 } } } }, "429": { "description": "Bulk delete cooldown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "Aliases": { "type": "array", "items": { "type": "string" }, "description": "Alias addresses to delete." } }, "required": [ "Aliases" ] } } } } } }, "/v1/get/delete/alias/bulk": { "get": { "summary": "Get Bulk Delete Aliases Task", "description": "Poll bulk alias delete task status.\n\nHeader auth required: `Authorization: Bearer ` or `X-Api-Key`.", "tags": [ "Mails.now" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "Task_id": 126, "status": "completed", "results": [], "task_id": "126" } } } }, "404": { "description": "Task ID was not found for this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "task_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Task id from delete endpoint." } ] } }, "/v1/mail/inbound": { "post": { "summary": "Inbound Email", "description": "Accepts inbound payloads for a tenant mailbox and queues processing. Optional fields include `from_name`, `cc`, `bcc`, `body_html`, `attachments`, and `headers`.\n\nRequires API key with `inbound` permission.\n\nInbound processing is asynchronous.", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "accepted", "message_id": "" } } } }, "401": { "description": "API key is required or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks inbound permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Duplicate message_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Unknown mailbox or invalid payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message_id": { "type": "string", "description": "Upstream message identifier. Must be unique per mailbox." }, "from_email": { "type": "string", "description": "Sender email address." }, "to_email": { "type": "string", "description": "Recipient mailbox address owned by your tenant." }, "subject": { "type": "string", "description": "Email subject line." }, "received_at": { "type": "string", "description": "Inbound receive timestamp." } }, "required": [ "message_id", "from_email", "to_email", "subject", "received_at" ] } } } } } }, "/v1/emails": { "get": { "summary": "List Emails", "description": "Returns tenant-scoped inbox emails with cursor pagination.\n\nRequires API key with `read` permission.\n\nQuery is always tenant-isolated.", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [], "meta": { "next_cursor": null, "prev_cursor": null } } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks read permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "mailbox_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filter by mailbox." }, { "name": "unread", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Return unread only." }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter received_at lower bound." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter received_at upper bound." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search subject, body text, or sender address." } ] } }, "/v1/emails/{email}": { "get": { "summary": "Get Email", "description": "Returns one tenant-scoped email with attachment metadata.\n\nRequires API key with `read` permission.\n\nSoft-deleted records are not returned from this endpoint.", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": 123 } } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Email not found in your tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Email record ID (route parameter `{email}`)." } ] }, "delete": { "summary": "Delete Email", "description": "Soft-deletes an email and emits an email.deleted webhook event.\n\nRequires API key with `write` permission.\n\nRecord is soft deleted, not permanently removed.", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks write permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Email not found in your tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Email record ID (route parameter `{email}`)." } ] } }, "/v1/emails/sync": { "get": { "summary": "Sync Emails", "description": "Incremental polling endpoint for new, updated, and deleted emails.\n\nRequires API key with `read` permission.\n\nDeleted emails are returned with deletion markers to support tombstones.", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [], "meta": { "next_cursor": null, "prev_cursor": null } } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The since field is required and must be a valid date.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "since", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Sync lower bound using updated markers." } ] } }, "/v1/emails/{email}/read": { "post": { "summary": "Mark Email Read", "description": "Marks an email as read and emits an email.read webhook event.\n\nRequires API key with `write` permission.\n\nThis endpoint is idempotent.", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks write permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Email not found in your tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Email record ID (route parameter `{email}`)." } ] } }, "/v1/emails/{email}/attachments/{attachment}": { "get": { "summary": "Attachment URL", "description": "Returns a temporary signed attachment download URL.\n\nRequires API key with `read` permission.\n\nURL expires shortly after issuance.", "tags": [ "Inbox" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "url": "https://signed-url", "expires_at": "2026-04-28T10:10:00Z" } } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Email or attachment not found in your tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Email record ID (route parameter `{email}`)." }, { "name": "attachment", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Attachment record ID (route parameter `{attachment}`)." } ] } }, "/v1/webhooks": { "post": { "summary": "Register Webhook", "description": "Creates a tenant-scoped webhook target for email events.\n\nRequires API key with `webhook` permission.\n\nDeliveries are queued and signed using the webhook secret and timestamp headers.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": 1 } } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks webhook permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid URL or event selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Destination webhook URL." }, "events": { "type": "array", "items": { "type": "string" }, "description": "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." } }, "required": [ "url", "events" ] } } } } }, "get": { "summary": "List Webhooks", "description": "Returns tenant-scoped webhook endpoints.\n\nRequires API key with `webhook` permission.\n\nEach row includes `last_triggered_at` when the webhook has fired.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": 1, "url": "https://example.com/hook", "events": [ "email.received" ], "is_active": true } ] } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks webhook permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ] } }, "/v1/webhooks/{webhook}": { "patch": { "summary": "Update Webhook", "description": "Updates URL, events, or active state.\n\nRequires API key with `webhook` permission.\n\nInclude at least one of `url`, `events`, or `is_active`.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks webhook permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found in your tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid URL or event selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Webhook ID (route parameter `{webhook}`)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Destination webhook URL." }, "events": { "type": "array", "items": { "type": "string" }, "description": "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": { "type": "boolean", "description": "Whether webhook should receive deliveries." } } } } } } }, "delete": { "summary": "Delete Webhook", "description": "Deletes a tenant webhook endpoint.\n\nRequires API key with `webhook` permission.\n\nPermanent delete; queued delivery rows for this webhook are removed.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key lacks webhook permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Webhook not found in your tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Webhook ID (route parameter `{webhook}`)." } ] } }, "/v1/sequencer/campaigns": { "get": { "summary": "List Sequencer Campaigns", "description": "Returns paginated campaigns for the tenant.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [] } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by status (draft, active, paused)." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search campaign name." } ] }, "post": { "summary": "Create Campaign", "description": "Creates a draft campaign. Omitting sequence_id auto-provisions a linked sequence with default schedule.\n\nRequires API key with `sequencer` permission.\n\nAuto-provisioned campaigns include a default Mon–Fri 08:00–18:00 UTC sending window.\n\nAssign mailbox_ids before calling enroll.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "created" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Campaign name." }, "sequence_id": { "type": "integer", "description": "Existing sequence ID. Omitted values auto-provision a new sequence." }, "lead_list_id": { "type": "integer", "description": "Optional default lead list." }, "mailbox_ids": { "type": "array", "items": { "type": "string" }, "description": "Sender mailbox IDs for rotation. Required before enroll." }, "settings": { "type": "object", "description": "daily_send_limit, ramp_up_percent_per_day, ramp_up_mode (percent|count), track_opens, track_clicks, schedule_mode (now|future)." }, "sending_window": { "type": "object", "description": "days[], start_hour, start_minute, end_hour, end_minute." }, "sending_timezone": { "type": "string", "description": "IANA timezone (default UTC)." } }, "required": [ "name" ] } } } } } }, "/v1/sequencer/campaigns/{campaign}": { "get": { "summary": "Show Campaign", "description": "Returns campaign details with sequence and mailboxes.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [] } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "campaign", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Campaign ID." } ] }, "patch": { "summary": "Update Campaign", "description": "Updates campaign settings, schedule, mailboxes, or activates a draft campaign.\n\nRequires API key with `sequencer` permission.\n\nActivation from draft requires email steps, mailboxes, daily_send_limit > 0, enrolled leads, and a valid sending_window.\n\nActive campaigns cannot remove sender mailboxes via mailbox_ids; pause the campaign first.\n\nHTTP 422 responses include failures[] with human-readable reasons.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "updated" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "campaign", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Campaign ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Campaign name." }, "status": { "type": "string", "description": "Set to active on draft campaigns to launch (runs readiness checks)." }, "mailbox_ids": { "type": "array", "items": { "type": "string" }, "description": "Mailbox IDs for sender rotation. Active campaigns may add mailboxes but cannot drop existing ones (pause first)." }, "settings": { "type": "object", "description": "daily_send_limit, ramp_up_percent_per_day, ramp_up_mode (percent|count), track_opens, track_clicks, schedule_mode." }, "sending_window": { "type": "object", "description": "Active days and hours for sending." }, "sending_timezone": { "type": "string", "description": "IANA timezone." } } } } } } }, "delete": { "summary": "Delete Campaign", "description": "Deletes a campaign.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "deleted" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "campaign", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Campaign ID." } ] } }, "/v1/sequencer/campaigns/{campaign}/enroll": { "post": { "summary": "Enroll Leads in Campaign", "description": "Enrolls lead IDs or an entire lead list into a campaign.\n\nRequires API key with `sequencer` permission.\n\nReturns HTTP 422 when the campaign has no mailboxes configured.\n\nProvide lead_ids or lead_list_id (not both required, but at least one).", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "completed", "enrolled": 2, "skipped": 0 } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "campaign", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Campaign ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lead_ids": { "type": "array", "items": { "type": "string" }, "description": "Lead IDs to enroll." }, "lead_list_id": { "type": "integer", "description": "Lead list ID to bulk enroll." } } } } } } } }, "/v1/sequencer/campaigns/{campaign}/pause": { "post": { "summary": "Pause Campaign", "description": "Pauses an active campaign.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "updated" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "campaign", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Campaign ID." } ] } }, "/v1/sequencer/campaigns/{campaign}/resume": { "post": { "summary": "Resume Campaign", "description": "Resumes a paused campaign. Runs the same readiness checks as draft activation (email steps, mailboxes, daily limit, leads, schedule).\n\nRequires API key with `sequencer` permission.\n\nHTTP 422 when readiness checks fail; response includes reason and failures[].", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "updated" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "campaign", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Campaign ID." } ] } }, "/v1/sequencer/campaigns/{campaign}/analytics": { "get": { "summary": "Campaign Analytics", "description": "Returns funnel metrics, engagement rates, and breakdowns by mailbox, step, and domain.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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": [] } } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "campaign", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Campaign ID." } ] } }, "/v1/sequencer/sequences": { "get": { "summary": "List Sequences", "description": "Returns paginated email sequences for the tenant.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [] } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search sequence name." } ] }, "post": { "summary": "Create Sequence", "description": "Creates a sequence with optional initial steps.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "created" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Sequence name." }, "steps": { "type": "array", "items": { "type": "string" }, "description": "Initial step definitions." } }, "required": [ "name" ] } } } } } }, "/v1/sequencer/sequences/{sequence}": { "get": { "summary": "Show Sequence", "description": "Returns a sequence with steps.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [] } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "sequence", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Sequence ID." } ] }, "patch": { "summary": "Update Sequence", "description": "Updates sequence metadata and optional steps.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "updated" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "sequence", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Sequence ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Sequence name." } } } } } } }, "delete": { "summary": "Delete Sequence", "description": "Deletes a sequence.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "deleted" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "sequence", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Sequence ID." } ] } }, "/v1/sequencer/sequences/{sequence}/steps": { "put": { "summary": "Sync Sequence Steps", "description": "Replaces sequence steps in one request.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "updated" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "sequence", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Sequence ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "string" }, "description": "Ordered step payloads." } }, "required": [ "steps" ] } } } } } }, "/v1/sequencer/sequences/{sequence}/steps/{step}": { "delete": { "summary": "Delete Sequence Step", "description": "Deletes a single sequence step.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "deleted" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "sequence", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Sequence ID." }, { "name": "step", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Sequence step ID." } ] } }, "/v1/sequencer/leads": { "get": { "summary": "List Sequencer Leads", "description": "Returns tenant-scoped leads with cursor pagination.\n\nRequires API key with `sequencer` permission and sequencer_enabled plan feature.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [] } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by lead status." }, { "name": "list_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filter by lead list ID." }, { "name": "tag", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by tag name." }, { "name": "saved_filter_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Apply a saved filter." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search email, name, or company." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor for pagination." } ] }, "post": { "summary": "Create Sequencer Lead", "description": "Creates or updates a lead by email address.\n\nRequires API key with `sequencer` permission and sequencer_enabled plan feature.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "created", "data": { "email": "lead@example.com" } } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Lead email address." }, "first_name": { "type": "string", "description": "First name. Nullable." }, "last_name": { "type": "string", "description": "Last name. Nullable." }, "company": { "type": "string", "description": "Company name. Nullable." }, "title": { "type": "string", "description": "Job title. Nullable." }, "job_level": { "type": "string", "description": "Job level (e.g. manager, vp). Nullable." }, "department": { "type": "string", "description": "Department. Nullable." }, "experience": { "type": "string", "description": "Experience range (e.g. 5-10 years). Nullable." }, "person_address": { "type": "string", "description": "Person street address. Nullable." }, "person_city": { "type": "string", "description": "Person city. Nullable." }, "person_state": { "type": "string", "description": "Person state/region. Nullable." }, "person_country": { "type": "string", "description": "Person country. Nullable." }, "phone": { "type": "string", "description": "Phone number. Nullable." }, "linkedin_url": { "type": "string", "description": "Person LinkedIn URL. Nullable." }, "website": { "type": "string", "description": "Website URL. Nullable." }, "company_domain": { "type": "string", "description": "Company domain. Nullable." }, "industry": { "type": "string", "description": "Industry. Nullable." }, "employee_count": { "type": "string", "description": "Employee count or range (e.g. 51-200). Nullable." }, "annual_revenue": { "type": "string", "description": "Annual revenue or range (e.g. $10M-$50M). Nullable." }, "company_linkedin_url": { "type": "string", "description": "Company LinkedIn URL. Nullable." }, "company_address": { "type": "string", "description": "Company street address. Nullable." }, "company_city": { "type": "string", "description": "Company city. Nullable." }, "company_state": { "type": "string", "description": "Company state/region. Nullable." }, "company_country": { "type": "string", "description": "Company country. Nullable." }, "technologies": { "type": "array", "items": { "type": "string" }, "description": "List of technology strings. Nullable." }, "email_provider": { "type": "string", "description": "Email provider (e.g. google, microsoft). Nullable." }, "timezone": { "type": "string", "description": "IANA timezone. Nullable." }, "source": { "type": "string", "description": "Lead source. Nullable; defaults to api when omitted." }, "last_updated": { "type": "string", "description": "Enrichment freshness timestamp (parseable datetime). Nullable." }, "lead_score": { "type": "integer", "description": "Lead score (unsigned integer). Nullable." }, "custom_fields": { "type": "object", "description": "Arbitrary key/value bag for non-standard fields. Nullable." } }, "required": [ "email" ] } } } } } }, "/v1/sequencer/leads/import": { "post": { "summary": "Import Sequencer Leads", "description": "Bulk import leads via multipart file, raw CSV string, or leads[] array. ≤50 rows sync (201); >50 rows queued ApiTask (202).\n\nRequires API key with `sequencer` permission and sequencer_enabled plan feature.\n\nProvide one of file, csv, or leads.\n\nCSV/spreadsheet: first row is headers (case-insensitive); email column required. Unknown columns go into custom_fields.\n\nRecognized columns include first_name, last_name, company, title, phone, linkedin_url, website, company_domain, industry, timezone, source, lead_score.\n\nAsync imports return task_id; poll GET /api/v1/sequencer/leads/import/{task}.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "completed", "mode": "sync", "created": 1 } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "string", "description": "Multipart upload field. Accepts csv, txt, xlsx, xls. Max 10 MB. Use multipart/form-data (omit Content-Type: application/json)." }, "csv": { "type": "string", "description": "Raw CSV string in JSON body. Max 10 KB. First row must be headers including email." }, "leads": { "type": "array", "items": { "type": "string" }, "description": "Lead objects (max 1000). Each row requires email; optional first_name, last_name, company, title, phone, and other lead fields." } } } } } } } }, "/v1/sequencer/leads/import/{task}": { "get": { "summary": "Import Task Status", "description": "Poll async lead import task progress.\n\nRequires API key with `sequencer` permission and sequencer_enabled plan feature.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [] } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "task", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ApiTask ID from async import." } ] } }, "/v1/sequencer/leads/{lead}": { "get": { "summary": "Show Sequencer Lead", "description": "Returns a single lead with tags and metadata.\n\nRequires API key with `sequencer` permission and sequencer_enabled plan feature.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [] } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "lead", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Lead ID." } ] }, "patch": { "summary": "Update Sequencer Lead", "description": "Updates lead profile fields and status.\n\nRequires API key with `sequencer` permission and sequencer_enabled plan feature.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "updated" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "lead", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Lead ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "description": "First name." }, "status": { "type": "string", "description": "Lead status enum value." } } } } } } }, "delete": { "summary": "Delete Sequencer Lead", "description": "Deletes a lead from the tenant workspace.\n\nRequires API key with `sequencer` permission and sequencer_enabled plan feature.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "deleted" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "lead", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Lead ID." } ] } }, "/v1/sequencer/lead-tags": { "get": { "summary": "List Lead Tags", "description": "Returns paginated Lead Tags for the tenant.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [] } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ] }, "post": { "summary": "Create Lead Tag", "description": "Creates a Lead Tag.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "created" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Tag name." }, "color": { "type": "string", "description": "Hex color." } }, "required": [ "name" ] } } } } } }, "/v1/sequencer/lead-tags/{leadTag}": { "get": { "summary": "Show Lead Tag", "description": "Returns a single Lead Tag.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [] } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "leadTag", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Lead Tag ID." } ] }, "patch": { "summary": "Update Lead Tag", "description": "Updates a Lead Tag.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "updated" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "leadTag", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Lead Tag ID." } ] }, "delete": { "summary": "Delete Lead Tag", "description": "Deletes a Lead Tag.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "deleted" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "leadTag", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Lead Tag ID." } ] } }, "/v1/sequencer/lead-lists": { "get": { "summary": "List Lead Lists", "description": "Returns paginated Lead Lists for the tenant.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [] } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ] }, "post": { "summary": "Create Lead List", "description": "Creates a Lead List.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "created" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "List name." }, "description": { "type": "string", "description": "Optional description." }, "lead_ids": { "type": "array", "items": { "type": "string" }, "description": "Initial member lead IDs." } }, "required": [ "name" ] } } } } } }, "/v1/sequencer/lead-lists/{leadList}": { "get": { "summary": "Show Lead List", "description": "Returns a single Lead List.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [] } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "leadList", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Lead List ID." } ] }, "patch": { "summary": "Update Lead List", "description": "Updates a Lead List.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "updated" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "leadList", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Lead List ID." } ] }, "delete": { "summary": "Delete Lead List", "description": "Deletes a Lead List.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "deleted" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "leadList", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Lead List ID." } ] } }, "/v1/sequencer/lead-notes": { "get": { "summary": "List Lead Notes", "description": "Returns paginated Lead Notes for the tenant.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [] } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ] }, "post": { "summary": "Create Lead Note", "description": "Creates a Lead Note.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "created" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lead_id": { "type": "integer", "description": "Lead ID." }, "body": { "type": "string", "description": "Note body." } }, "required": [ "lead_id", "body" ] } } } } } }, "/v1/sequencer/lead-notes/{leadNote}": { "get": { "summary": "Show Lead Note", "description": "Returns a single Lead Note.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [] } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "leadNote", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Lead Note ID." } ] }, "patch": { "summary": "Update Lead Note", "description": "Updates a Lead Note.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "updated" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "leadNote", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Lead Note ID." } ] }, "delete": { "summary": "Delete Lead Note", "description": "Deletes a Lead Note.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "deleted" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "leadNote", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Lead Note ID." } ] } }, "/v1/sequencer/saved-filters": { "get": { "summary": "List Saved Filters", "description": "Returns paginated Saved Filters for the tenant.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [] } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ] }, "post": { "summary": "Create Saved Filter", "description": "Creates a Saved Filter.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "created" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Filter name." }, "filters": { "type": "object", "description": "Filter criteria (status, q, tag, list_id)." } }, "required": [ "name", "filters" ] } } } } } }, "/v1/sequencer/saved-filters/{savedFilter}": { "get": { "summary": "Show Saved Filter", "description": "Returns a single Saved Filter.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [] } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "savedFilter", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Saved Filter ID." } ] }, "patch": { "summary": "Update Saved Filter", "description": "Updates a Saved Filter.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "updated" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "savedFilter", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Saved Filter ID." } ] }, "delete": { "summary": "Delete Saved Filter", "description": "Deletes a Saved Filter.\n\nRequires API key with `sequencer` permission.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "deleted" } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "savedFilter", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Saved Filter ID." } ] } }, "/v1/sequencer/leads/webhook": { "post": { "summary": "Webhook Create Lead", "description": "Creates a lead from an inbound webhook payload.\n\nRequires API key with `sequencer` permission and sequencer_enabled plan feature.", "tags": [ "Sequencer" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [] } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Plan does not include Email Sequencer or key lacks permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found in tenant scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Lead email address." }, "list_id": { "type": "integer", "description": "Optional lead list to attach." } }, "required": [ "email" ] } } } } } }, "/v1/transactional/send": { "post": { "summary": "Send Transactional Email", "description": "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.\n\nRequires API key with `transactional` permission and plan feature `transactional_enabled`.\n\nHTTP 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.\n\n`status` is queue/SMTP acceptance; inbox confirmation is `delivered_at` / `delivery_events`.\n\nDo not send `subject`, `message`, or `text`; they are prohibited. Design the template under Transactional → Email Templates.\n\nNo List-Unsubscribe headers are injected for transactional sends.\n\nOpen/click tracking follows the template `track_opens` / `track_clicks` flags.\n\nThrottled at 60 requests/min per API key (`api-v1-transactional`).", "tags": [ "Transactional" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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 } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Your current plan does not include Transactional Email. API key does not have transactional permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "This idempotency_key was already used for a different send. Use a unique key per logical send, or omit idempotency_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Do not send subject; it is taken from the saved message template. This message has no saved template. The from email must belong to one of your mailboxes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transactional_message_id": { "type": "integer", "description": "Tenant template ID. Must be enabled and have a saved subject plus HTML." }, "to": { "type": "object", "description": "`email` (required), `name` (optional)." }, "from": { "type": "object", "description": "`email` must match a tenant mailbox (case-insensitive). `name` optional; defaults to mailbox display name." }, "variables": { "type": "object", "description": "Key/value map for `{{token}}` substitution in the saved template." }, "reply_to": { "type": "string", "description": "Optional reply-to address." }, "headers": { "type": "object", "description": "Custom headers. Only names starting with `X-` / `x-` are stored; others are dropped." }, "idempotency_key": { "type": "string", "description": "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": { "type": "array", "items": { "type": "string" }, "description": "Optional base64 attachments (`filename`, `content_type`, `content`). Count/size/MIME limits in `config/transactional.php`." } }, "required": [ "transactional_message_id", "to", "from" ] } } } } } }, "/v1/transactional/messages": { "get": { "summary": "List Transactional Messages", "description": "Lists transactional templates for the authenticated tenant (enabled and disabled). Bodies are not included.\n\nRequires API key with `transactional` permission and plan feature `transactional_enabled`.\n\nCreate and edit templates in the dashboard under Transactional → Email Templates. There is no REST create/update for templates.\n\nResponse is a Laravel paginated resource (`data`, `links`, `meta`), not `{status: success}`.\n\n`slug` is nullable; send/list identify templates by `id`.\n\nDashboard-created rows use `source` `manual`. HTML and plaintext are omitted from this list.\n\nMCP `list_transactional_messages` returns enabled templates only; this REST list includes disabled rows.", "tags": [ "Transactional" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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" } ] } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key does not have transactional permission. Your current plan does not include Transactional Email.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Page size (1–100, default 50)." } ] } }, "/v1/transactional/sends/{outboundEmail}": { "get": { "summary": "Get Transactional Send", "description": "Shows a single transactional outbound send for the tenant.\n\nRequires API key with `transactional` permission and plan feature `transactional_enabled`.\n\nNon-transactional outbound rows (compose, sequencer, SMTP gateway) return 404.\n\n`status` is queue/SMTP acceptance; `delivered_at` and `delivery_events` reflect provider delivery webhooks.", "tags": [ "Transactional" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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": "", "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 } ] } } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key does not have transactional permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Send not found in your tenant scope or not transactional.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "parameters": [ { "name": "outboundEmail", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Outbound email ID." } ] } }, "/v1/transactional/variables": { "post": { "summary": "Create or Overwrite Variable", "description": "Registers a typed variable in the tenant Variable Manager. Duplicate keys return HTTP 409 unless `overwrite=true`.\n\nRequires API key with `transactional` permission and plan feature `transactional_enabled`.\n\nHTTP 201 on create; HTTP 200 when overwriting an existing key (`overwritten: true`).\n\nDuplicate keys never silently overwrite without `overwrite=true`.\n\nWhen any registry rows exist, send rejects unregistered `{{token}}` keys used in the template.", "tags": [ "Transactional" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success", "data": { "id": 1, "key": "otp", "data_type": "integer", "default_value": null, "source": "api" }, "overwritten": false } } } }, "401": { "description": "Invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key does not have transactional permission. Your current plan does not include Transactional Email.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A variable with this key already exists. Pass overwrite=true to replace it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The variable key may only contain letters, numbers, underscores, dots, and hyphens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "BearerAuth": [] }, { "ApiKeyHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "Variable key used in `{{key}}` tokens (letters, numbers, `_`, `.`, `-`; max 64)." }, "data_type": { "type": "string", "description": "One of: string, integer, date, url, boolean, email, currency." }, "default_value": { "type": "string", "description": "Applied when the send payload omits the variable (max 2000)." }, "overwrite": { "type": "boolean", "description": "When true, replaces an existing key instead of returning 409." } }, "required": [ "key", "data_type" ] } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Send API keys via `Authorization: Bearer ` or `X-Api-Key` headers only." }, "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "32 characters (alpha-numeric)" } }, "schemas": { "ErrorResponse": { "type": "object", "required": [ "status", "reason" ], "properties": { "status": { "type": "string", "enum": [ "error" ] }, "reason": { "type": "string" } } }, "TaskResponse": { "type": "object", "required": [ "status", "task_id" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "task_id": { "type": "integer" }, "domain": { "type": "string" } } } } } }