{ "openapi": "3.0.0", "paths": { "/v1/api-keys": { "post": { "description": "Mint a new key for your workspace. The full token is returned **once**, so store it immediately. Requested scopes must be a subset of the calling key’s own scopes, and cannot include `apikeys:manage`.\n\nRequires the `apikeys:manage` scope, which no wildcard grants and which can only be created from the dashboard.", "operationId": "apiKeys_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyDto" } } } }, "responses": { "201": { "description": "Key created; token returned once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create an API key", "tags": [ "API Keys" ] }, "get": { "description": "All keys in the caller’s workspace, with masked prefixes (no secrets).\n\nRequires the `apikeys:manage` scope, which no wildcard grants and which can only be created from the dashboard.", "operationId": "apiKeys_list", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyListResponseDto" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List API keys", "tags": [ "API Keys" ] } }, "/v1/api-keys/{id}": { "delete": { "description": "Delete a key by id. It stops working immediately and is removed from the list. Cannot be undone.\n\nRequires the `apikeys:manage` scope, which no wildcard grants and which can only be created from the dashboard.", "operationId": "apiKeys_delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The API key id.", "schema": { "format": "uuid", "example": "5b8e1d90-3c47-4a26-9f01-7ea2c6d5b483", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`.", "required": false, "schema": { "type": "string", "maxLength": 255, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "Key deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeApiKeyResponseDto" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "409": { "description": "The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with an existing resource.", "status": 409, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "422": { "description": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "status": 422, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Delete an API key", "tags": [ "API Keys" ] } }, "/v1/campaigns/{cid}/leads": { "get": { "description": "Page through a campaign’s leads with filters (status, tags, search, engagement: opened / clicked / not opened).\n\nRequires one of the following scopes: `leads:read`, `leads:all`, `all:read`, `all:all`.", "operationId": "campaignLeads_list", "parameters": [ { "name": "cid", "required": true, "in": "path", "schema": { "format": "uuid", "example": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60", "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from a previous response’s `meta.nextCursor`. Omit for the first page. Results are ordered newest-first and stable under concurrent changes.", "schema": { "example": "eyJ0cyI6IjIwMjYtMDctMDJUMDA6MDA6MDAuMDAwWiIsImlkIjoiM2YxYzJiN2UtOWE0ZC00ZTE4LWIyYzEtNmQ4ZjVhMGU3YzkzIn0", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 250, "default": 50, "example": 50, "type": "number" } }, { "name": "search", "required": false, "in": "query", "description": "Match on email / first name / last name / company.", "schema": { "example": "acme", "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "Filter by lead status.", "schema": { "type": "string", "enum": [ "not_contacted", "scheduled", "email_sent", "failed", "skipped", "lead_replied_interested", "lead_replied_meeting_request", "lead_replied_out_of_office", "lead_replied_bounce", "lead_replied_wrong_person", "lead_replied_not_interested", "lead_replied_unsubscribed", "lead_replied_uncategorized", "lead_converted", "lead_lost", "blacklisted" ] } }, { "name": "tags", "required": false, "in": "query", "description": "Has ANY of these tags. Repeat the param (`?tags=a&tags=b`) or pass a single value.", "schema": { "example": [ "vip", "q4" ], "type": "array", "items": { "type": "string" } } }, { "name": "engagement", "required": false, "in": "query", "description": "Filter by engagement. `opened` — opened at least one email; `opened_no_reply` — opened and has not replied (any reply counts, out-of-office and auto-replies included); `clicked` — clicked a tracked link; `not_opened` — was sent at least one email with open tracking and opened none.", "schema": { "type": "string", "enum": [ "opened", "opened_no_reply", "clicked", "not_opened" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadListApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List campaign leads", "tags": [ "Leads" ] }, "post": { "description": "Add 1-100 leads to a campaign. Each is deduplicated by email within the campaign and provider-detected. The response summarizes the outcome and returns the created leads.\n\nRequires one of the following scopes: `leads:write`, `leads:all`, `all:all`.", "operationId": "campaignLeads_add", "parameters": [ { "name": "cid", "required": true, "in": "path", "schema": { "format": "uuid", "example": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`.", "required": false, "schema": { "type": "string", "maxLength": 255, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddLeadsApiDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddLeadsApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "402": { "description": "A plan limit was reached - top up or upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "plan_limit_exceeded", "message": "A plan limit was reached.", "status": 402, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "409": { "description": "The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with an existing resource.", "status": 409, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "422": { "description": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "status": 422, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Add leads", "tags": [ "Leads" ] } }, "/v1/campaigns/{cid}/leads/{leadId}": { "get": { "description": "One lead including live sequence progress (steps sent/planned, next send).\n\nRequires one of the following scopes: `leads:read`, `leads:all`, `all:read`, `all:all`.", "operationId": "campaignLeads_get", "parameters": [ { "name": "cid", "required": true, "in": "path", "schema": { "format": "uuid", "example": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60", "type": "string" } }, { "name": "leadId", "required": true, "in": "path", "schema": { "format": "uuid", "example": "c9e5b1a3-7f24-4d80-a6b9-2e4f8c0d1a37", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadApiDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get a lead", "tags": [ "Leads" ] }, "patch": { "description": "Update a lead’s fields, tags, custom fields, or status. The email address can only be changed while the lead has not been contacted yet. Reply-based statuses can only be set once the lead has replied.\n\nRequires one of the following scopes: `leads:write`, `leads:all`, `all:all`.", "operationId": "campaignLeads_update", "parameters": [ { "name": "cid", "required": true, "in": "path", "schema": { "format": "uuid", "example": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60", "type": "string" } }, { "name": "leadId", "required": true, "in": "path", "schema": { "format": "uuid", "example": "c9e5b1a3-7f24-4d80-a6b9-2e4f8c0d1a37", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`.", "required": false, "schema": { "type": "string", "maxLength": 255, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLeadApiDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadApiDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "409": { "description": "The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with an existing resource.", "status": 409, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "422": { "description": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "status": 422, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Update a lead", "tags": [ "Leads" ] }, "delete": { "description": "Remove a single lead. Contacted leads are soft-deleted with a retention window.\n\nRequires one of the following scopes: `leads:write`, `leads:all`, `all:all`.", "operationId": "campaignLeads_remove", "parameters": [ { "name": "cid", "required": true, "in": "path", "schema": { "format": "uuid", "example": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60", "type": "string" } }, { "name": "leadId", "required": true, "in": "path", "schema": { "format": "uuid", "example": "c9e5b1a3-7f24-4d80-a6b9-2e4f8c0d1a37", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`.", "required": false, "schema": { "type": "string", "maxLength": 255, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteLeadApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "409": { "description": "The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with an existing resource.", "status": 409, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "422": { "description": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "status": 422, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Delete a lead", "tags": [ "Leads" ] } }, "/v1/campaigns/{cid}/leads/mutate": { "post": { "description": "Apply one operation (`set_status`, `add_tags`, `remove_tags`, or `delete`) across many leads. Target them by `ids`; `delete` also accepts a `filter`, or `all: true` to remove every lead. Reply-based statuses can only be set on leads that have already replied.\n\nRequires one of the following scopes: `leads:write`, `leads:all`, `all:all`.", "operationId": "campaignLeads_mutate", "parameters": [ { "name": "cid", "required": true, "in": "path", "schema": { "format": "uuid", "example": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`.", "required": false, "schema": { "type": "string", "maxLength": 255, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutateLeadsApiDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutateLeadsApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "409": { "description": "The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with an existing resource.", "status": 409, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "422": { "description": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "status": 422, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Bulk mutate leads", "tags": [ "Leads" ] } }, "/v1/leads/search": { "get": { "description": "Find leads across all of the workspace’s campaigns by email (or fragment), for dedupe and cross-campaign lookup. Returns up to 10 matches.\n\nRequires one of the following scopes: `leads:read`, `leads:all`, `all:read`, `all:all`.", "operationId": "leads_search", "parameters": [ { "name": "email", "required": true, "in": "query", "description": "Email (or fragment) to search for. Case-insensitive.", "schema": { "example": "jane@acme.com", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadSearchApiResponseDto" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Search leads by email", "tags": [ "Leads" ] } }, "/v1/campaigns": { "post": { "description": "Create a campaign with its schedule, settings, sequence (with A/B variants), sending accounts, tags, and optionally its leads, in one call. Set `launch: true` to start it right away, which also needs the `campaigns:lifecycle` scope. If it cannot launch, the campaign is still created and `launchError` says why.\n\nRequires one of the following scopes: `campaigns:write`, `campaigns:all`, `all:all`.", "operationId": "campaigns_create", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`.", "required": false, "schema": { "type": "string", "maxLength": 255, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCampaignApiDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCampaignApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "409": { "description": "The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with an existing resource.", "status": 409, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "422": { "description": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "status": 422, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Create a campaign", "tags": [ "Campaigns" ] }, "get": { "description": "Cursor-paginate the workspace campaigns (id, name, status, lead count), newest-first and stable under concurrent changes.\n\nRequires one of the following scopes: `campaigns:read`, `campaigns:all`, `all:read`, `all:all`.", "operationId": "campaigns_list", "parameters": [ { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from a previous response’s `meta.nextCursor`. Omit for the first page. Results are ordered newest-first and stable under concurrent changes.", "schema": { "example": "eyJ0cyI6IjIwMjYtMDctMDJUMDA6MDA6MDAuMDAwWiIsImlkIjoiM2YxYzJiN2UtOWE0ZC00ZTE4LWIyYzEtNmQ4ZjVhMGU3YzkzIn0", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "integer" } }, { "name": "status", "required": false, "in": "query", "description": "Filter by campaign status.", "schema": { "type": "string", "enum": [ "draft", "scheduled", "active", "paused", "stopped", "completed", "failed" ] } }, { "name": "tags", "required": false, "in": "query", "description": "Only campaigns carrying at least ONE of these tag ids (comma-separated). Read the ids from `tags[]` on any campaign; tags themselves are managed in the dashboard.", "schema": { "example": "5c9b1e77-2f4a-4c31-9d8e-1a2b3c4d5e6f,7a1d2e88-3b5c-4d62-8e9f-2b3c4d5e6f70", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignListApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List campaigns", "tags": [ "Campaigns" ] } }, "/v1/campaigns/{id}": { "get": { "description": "Full config - schedule, settings, sequence steps, attached accounts, headline metrics.\n\nRequires one of the following scopes: `campaigns:read`, `campaigns:all`, `all:read`, `all:all`.", "operationId": "campaigns_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "example": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignApiDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get a campaign", "tags": [ "Campaigns" ] }, "patch": { "description": "Partial update - only the supplied sections are touched. `accounts`, `tags` and `sequence`, when present, REPLACE the existing set.\n\nRequires one of the following scopes: `campaigns:write`, `campaigns:all`, `all:all`.", "operationId": "campaigns_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "example": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`.", "required": false, "schema": { "type": "string", "maxLength": 255, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCampaignApiDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignApiDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "409": { "description": "The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with an existing resource.", "status": 409, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "422": { "description": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "status": 422, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Update a campaign", "tags": [ "Campaigns" ] }, "delete": { "description": "Delete a campaign to clean up programmatically-created resources.\n\nRequires one of the following scopes: `campaigns:write`, `campaigns:all`, `all:all`.", "operationId": "campaigns_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "example": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`.", "required": false, "schema": { "type": "string", "maxLength": 255, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteCampaignApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "409": { "description": "The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with an existing resource.", "status": 409, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "422": { "description": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "status": 422, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Delete a campaign", "tags": [ "Campaigns" ] } }, "/v1/campaigns/{id}/start": { "post": { "description": "Begin sending (or resume a paused campaign). Needs a lead list and a sequence - returns 400 if the campaign has nothing to send.\n\nRequires one of the following scopes: `campaigns:lifecycle`, `campaigns:all`, `all:all`.", "operationId": "campaigns_start", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "example": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`.", "required": false, "schema": { "type": "string", "maxLength": 255, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignLifecycleApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "409": { "description": "The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with an existing resource.", "status": 409, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "422": { "description": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "status": 422, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Start campaign", "tags": [ "Campaigns" ] } }, "/v1/campaigns/{id}/pause": { "post": { "description": "Pause an active campaign. In-flight sends finish; nothing new is scheduled.\n\nRequires one of the following scopes: `campaigns:lifecycle`, `campaigns:all`, `all:all`.", "operationId": "campaigns_pause", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "example": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`.", "required": false, "schema": { "type": "string", "maxLength": 255, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignLifecycleApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "409": { "description": "The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with an existing resource.", "status": 409, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "422": { "description": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "status": 422, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Pause campaign", "tags": [ "Campaigns" ] } }, "/v1/campaigns/{id}/resume": { "post": { "description": "Resume a paused campaign from where it left off. Returns 400 if the workspace has no email account at all; an account that exists but cannot send right now (disconnected, reauthorizing, DNS below the sending floor) does not block the resume.\n\nRequires one of the following scopes: `campaigns:lifecycle`, `campaigns:all`, `all:all`.", "operationId": "campaigns_resume", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "example": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`.", "required": false, "schema": { "type": "string", "maxLength": 255, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignLifecycleApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "409": { "description": "The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with an existing resource.", "status": 409, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "422": { "description": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "status": 422, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Resume campaign", "tags": [ "Campaigns" ] } }, "/v1/campaigns/{id}/status": { "get": { "description": "Lightweight live send-state (running/paused/completed), schedule-window state, and headline metrics. Deep reporting lives under the analytics endpoints.\n\nRequires one of the following scopes: `campaigns:read`, `campaigns:all`, `all:read`, `all:all`.", "operationId": "campaigns_status", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "example": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignStatusApiDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Campaign send status", "tags": [ "Campaigns" ] } }, "/v1/campaigns/{id}/test-email": { "post": { "description": "Send yourself a rendered preview of one step variant before launching. It goes from a real mailbox and counts toward that mailbox's daily limit, but not your monthly quota. Capped at 12 per day per workspace.\n\nRequires one of the following scopes: `campaigns:lifecycle`, `campaigns:all`, `all:all`.", "operationId": "campaigns_sendTestEmail", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "example": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`.", "required": false, "schema": { "type": "string", "maxLength": 255, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendTestEmailApiDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestEmailApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "409": { "description": "The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with an existing resource.", "status": 409, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "422": { "description": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "status": 422, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } }, "503": { "description": "A dependency is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "api_error", "code": "upstream_unavailable", "message": "A dependency is temporarily unavailable.", "status": 503, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Send a test email", "tags": [ "Campaigns" ] } }, "/v1/usage": { "get": { "description": "Everything you have used and everything you have left, grouped by product: your Email Outreach plan limits and your Lead Finder credits. Check it before a large send or import. For billing cycles and renewal dates, see `GET /v1/account/subscription`.\n\nRequires one of the following scopes: `usage:read`, `all:read`, `all:all`.", "operationId": "workspace_usage", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponseDto" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Current usage", "tags": [ "Workspace" ] } }, "/v1/usage/{limitType}": { "get": { "description": "Just one limit (used/limit/remaining/percentage/isUnlimited) - handy when you only care about the one you’re about to spend.\n\nRequires one of the following scopes: `usage:read`, `all:read`, `all:all`.", "operationId": "workspace_usageForLimit", "parameters": [ { "name": "limitType", "required": true, "in": "path", "description": "The limit to read.", "schema": { "enum": [ "monthly_emails", "active_contacts", "ai_credits", "email_validation", "lead_finder_credits" ], "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageLimitDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Current usage for one limit", "tags": [ "Workspace" ] } }, "/v1/account/subscription": { "get": { "description": "Everything you pay for, grouped by product: your Email Outreach subscription and your separate Lead Finder subscription. Each has its own plan, status, and billing cycle.\n\nRequires one of the following scopes: `usage:read`, `all:read`, `all:all`.", "operationId": "workspace_subscription", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponseDto" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Subscription", "tags": [ "Workspace" ] } }, "/v1/workspace": { "get": { "description": "Who this key belongs to - your workspace name and timezone. (Your plan lives in `GET /v1/usage` and `GET /v1/account/subscription`.)\n\nRequires one of the following scopes: `usage:read`, `all:read`, `all:all`.", "operationId": "workspace_workspace", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceResponseDto" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Workspace identity", "tags": [ "Workspace" ] } }, "/v1/accounts": { "post": { "description": "Connect one SMTP/IMAP mailbox, or up to 50 at once. Any provider works, including Gmail and Outlook with an app password. There is no limit on how many mailboxes a workspace may connect.\n\nRequires one of the following scopes: `accounts:write`, `accounts:all`, `all:all`.", "operationId": "accounts_create", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`.", "required": false, "schema": { "type": "string", "maxLength": 255, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountsApiDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountsApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "409": { "description": "The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with an existing resource.", "status": 409, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "422": { "description": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "status": 422, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Connect mailboxes", "tags": [ "Email Accounts" ] }, "get": { "description": "List your mailboxes, newest first, with stable cursor pagination. Filter by `status` or `tags` (any-of), or pass `email` to look one mailbox up by its address instead of by `id`.\n\nRequires one of the following scopes: `accounts:read`, `accounts:all`, `all:read`, `all:all`.", "operationId": "accounts_list", "parameters": [ { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from a previous response’s `meta.nextCursor`.", "schema": { "example": "eyJ0cyI6IjIwMjYtMDctMDJUMDA6MDA6MDAuMDAwWiIsImlkIjoiM2YxYzJiN2UtOWE0ZC00ZTE4LWIyYzEtNmQ4ZjVhMGU3YzkzIn0", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 250, "default": 50, "example": 50, "type": "number" } }, { "name": "status", "required": false, "in": "query", "description": "Filter by lifecycle status.", "schema": { "type": "string", "enum": [ "active", "inactive", "checking", "revoked", "failed" ] } }, { "name": "email", "required": false, "in": "query", "description": "Look a mailbox up by its address (exact, case-insensitive) instead of by `id`. Returns at most one mailbox, or an empty `data` array if you have no mailbox with that address.", "schema": { "example": "jane@acme.com", "type": "string" } }, { "name": "tags", "required": false, "in": "query", "description": "Only mailboxes carrying at least ONE of these tag ids (comma-separated). Read the ids from `tags[]` on any mailbox; tags themselves are managed in the dashboard.", "schema": { "example": "5c9b1e77-2f4a-4c31-9d8e-1a2b3c4d5e6f,7a1d2e88-3b5c-4d62-8e9f-2b3c4d5e6f70", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountListApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List mailboxes", "tags": [ "Email Accounts" ] } }, "/v1/accounts/{id}": { "get": { "description": "Fetch one mailbox with its embedded status, health score, and verification snapshot.\n\nRequires one of the following scopes: `accounts:read`, `accounts:all`, `all:read`, `all:all`.", "operationId": "accounts_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "example": "3f1c2b7e-9a4d-4e18-b2c1-6d8f5a0e7c93", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountApiDto" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get a mailbox", "tags": [ "Email Accounts" ] }, "patch": { "description": "Update a mailbox’s settings and limits, and rotate its SMTP/IMAP credentials. The email address cannot be changed. Including any `smtp*` or `imap*` field rotates the credentials and re-runs verification.\n\nRequires one of the following scopes: `accounts:write`, `accounts:all`, `all:all`.", "operationId": "accounts_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "example": "3f1c2b7e-9a4d-4e18-b2c1-6d8f5a0e7c93", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`.", "required": false, "schema": { "type": "string", "maxLength": 255, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAccountApiDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountApiDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "409": { "description": "The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with an existing resource.", "status": 409, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "422": { "description": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "status": 422, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Update a mailbox", "tags": [ "Email Accounts" ] }, "delete": { "description": "Delete a mailbox from your workspace. Sending from it stops immediately.\n\nRequires one of the following scopes: `accounts:write`, `accounts:all`, `all:all`.", "operationId": "accounts_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "example": "3f1c2b7e-9a4d-4e18-b2c1-6d8f5a0e7c93", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`.", "required": false, "schema": { "type": "string", "maxLength": 255, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAccountApiResponseDto" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "409": { "description": "The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with an existing resource.", "status": 409, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "422": { "description": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "status": 422, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Delete a mailbox", "tags": [ "Email Accounts" ] } }, "/v1/accounts/bulk": { "post": { "description": "Apply ONE settings/limits `patch` OR one `status` change (`active`/`inactive`) across many mailboxes. `patch` and `status` are mutually exclusive.\n\nRequires one of the following scopes: `accounts:write`, `accounts:all`, `all:all`.", "operationId": "accounts_bulk", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`.", "required": false, "schema": { "type": "string", "maxLength": 255, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAccountsApiDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAccountsApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "409": { "description": "The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with an existing resource.", "status": 409, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "422": { "description": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "status": 422, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Bulk update mailboxes", "tags": [ "Email Accounts" ] } }, "/v1/accounts/{id}/verification": { "get": { "description": "The latest SMTP + IMAP + DNS verification result for a mailbox.\n\nRequires one of the following scopes: `accounts:read`, `accounts:all`, `all:read`, `all:all`.", "operationId": "accounts_verification", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "example": "3f1c2b7e-9a4d-4e18-b2c1-6d8f5a0e7c93", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountVerificationApiDto" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Verification result", "tags": [ "Email Accounts" ] } }, "/v1/accounts/{id}/pause": { "post": { "description": "Stop sending from an active mailbox. It stays paused until you `resume` it - campaigns and warmup both skip it, and nothing re-activates it on its own. Returns `400` if the mailbox is not currently active.\n\nRequires one of the following scopes: `accounts:write`, `accounts:all`, `all:all`.", "operationId": "accounts_pause", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "example": "3f1c2b7e-9a4d-4e18-b2c1-6d8f5a0e7c93", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`.", "required": false, "schema": { "type": "string", "maxLength": 255, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountApiDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "409": { "description": "The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with an existing resource.", "status": 409, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "422": { "description": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "status": 422, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Pause a mailbox", "tags": [ "Email Accounts" ] } }, "/v1/accounts/{id}/resume": { "post": { "description": "Start sending from a mailbox again. One you paused resumes immediately; one we stopped after repeated failures is re-verified first and only resumes if the check passes.\n\nRequires one of the following scopes: `accounts:write`, `accounts:all`, `all:all`.", "operationId": "accounts_resume", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "example": "3f1c2b7e-9a4d-4e18-b2c1-6d8f5a0e7c93", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`.", "required": false, "schema": { "type": "string", "maxLength": 255, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountApiDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "409": { "description": "The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with an existing resource.", "status": 409, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "422": { "description": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "status": 422, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Resume a mailbox", "tags": [ "Email Accounts" ] } }, "/v1/accounts/oauth/{provider}/init": { "post": { "description": "Start connecting a Google Workspace or Microsoft mailbox over OAuth. Returns a consent URL to open in a browser, plus a `state` handle. Once the owner grants access, poll `GET /v1/accounts/oauth/{provider}/status?state=…`.\n\nRequires one of the following scopes: `accounts:write`, `accounts:all`, `all:all`.", "operationId": "accounts_oauthInit", "parameters": [ { "name": "provider", "required": true, "in": "path", "schema": { "enum": [ "google", "microsoft" ], "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthInitApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Start OAuth connect", "tags": [ "Email Accounts" ] } }, "/v1/accounts/oauth/{provider}/status": { "get": { "description": "Poll a connect started with `init`. `pending` until the mailbox owner finishes consent, then `connected` (with `accountId`) or `failed`.\n\nRequires one of the following scopes: `accounts:read`, `accounts:all`, `all:read`, `all:all`.", "operationId": "accounts_oauthStatus", "parameters": [ { "name": "provider", "required": true, "in": "path", "schema": { "enum": [ "google", "microsoft" ], "type": "string" } }, { "name": "state", "required": true, "in": "query", "description": "The `state` returned by `init`.", "schema": { "example": "aB3dEf6hIjKlMnOpQrStUvWxYz0123456789_-AbCdE", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthStatusApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Poll OAuth connect", "tags": [ "Email Accounts" ] } }, "/v1/emails": { "get": { "description": "List emails across your mailboxes, newest first. Results carry a `snippet` preview but never the message body; fetch a single email to read it. Filter by mailbox, campaign, conversation, lead, read state, direction, folder, date, or full-text search.\n\nRequires one of the following scopes: `emails:read`, `emails:all`, `all:read`, `all:all`.", "operationId": "emails_list", "parameters": [ { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from a previous response’s `meta.nextCursor`.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "number" } }, { "name": "mailbox", "required": false, "in": "query", "description": "Filter by mailbox address, comma-separated. Addresses you do not own are ignored.", "schema": { "example": "jane@acme.com,sales@acme.com", "type": "string" } }, { "name": "campaignId", "required": false, "in": "query", "schema": { "example": "c1f3b0a2-6d4e-4f8b-9a1c-2e5d7f0a3b6c", "type": "string" } }, { "name": "threadId", "required": false, "in": "query", "description": "Return only emails in this conversation. Pass a `threadId` exactly as returned - it is opaque.", "schema": { "example": "13a265fd-f0f2-b1d1-d6fc-154e483183e7", "type": "string" } }, { "name": "leadId", "required": false, "in": "query", "schema": { "example": "9d4e2f10-5b6a-4c73-8e19-0f2a7c4d8b31", "type": "string" } }, { "name": "isUnread", "required": false, "in": "query", "description": "Filter by read state. Emails that are not part of a conversation have no read state and match neither `true` nor `false`.", "schema": { "example": true, "type": "boolean" } }, { "name": "type", "required": false, "in": "query", "schema": { "example": "received", "type": "string", "enum": [ "sent", "received" ] } }, { "name": "folder", "required": false, "in": "query", "description": "Return only emails whose conversation is in this folder - the same folders your team sees in the dashboard. `inbox`: campaign conversations someone replied to. `untracked`: conversations outside any campaign. `important`, `snoozed`, `archived`: as flagged in the dashboard - `important` spans the other folders. An email that belongs to no conversation is in no folder and matches none of these.", "schema": { "example": "inbox", "type": "string", "enum": [ "inbox", "untracked", "important", "snoozed", "archived" ] } }, { "name": "search", "required": false, "in": "query", "description": "Full-text search over subject, preview text and sender address. Supports quoted phrases, `OR` and `-exclude`.", "schema": { "example": "pricing question", "type": "string" } }, { "name": "latestOfThread", "required": false, "in": "query", "description": "Return one email per conversation: the most recent one that matches the rest of your filters. A cheap conversation-style view without fetching whole threads.\n\nThe filters are applied first, then the newest survivor of each conversation is kept – so `latestOfThread=true&type=received` gives you the last email each contact sent you, even in conversations you have already replied to. An email that belongs to no conversation is a conversation of one and is always kept.", "schema": { "example": true, "type": "boolean" } }, { "name": "since", "required": false, "in": "query", "schema": { "example": "2026-07-01T00:00:00.000Z", "type": "string" } }, { "name": "until", "required": false, "in": "query", "schema": { "example": "2026-07-14T00:00:00.000Z", "type": "string" } }, { "name": "sortOrder", "required": false, "in": "query", "description": "Order by received date. Defaults to newest first.", "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailListApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List emails", "tags": [ "Emails" ] } }, "/v1/emails/unread/count": { "get": { "description": "Number of unread emails, optionally narrowed to specific mailboxes or a campaign. Emails outside a conversation have no read state and are not counted.\n\nRequires one of the following scopes: `emails:read`, `emails:all`, `all:read`, `all:all`.", "operationId": "emails_unreadCount", "parameters": [ { "name": "mailbox", "required": false, "in": "query", "description": "Limit the count to these mailbox addresses, comma-separated.", "schema": { "example": "jane@acme.com", "type": "string" } }, { "name": "campaignId", "required": false, "in": "query", "schema": { "example": "c1f3b0a2-6d4e-4f8b-9a1c-2e5d7f0a3b6c", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnreadCountApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Count unread emails", "tags": [ "Emails" ] } }, "/v1/emails/{id}": { "get": { "description": "Fetch one email with its body – the only endpoint that returns the body. A `null` body means none was stored; if the stored body can't be read right now the call returns `503` rather than a false empty.\n\nRequires one of the following scopes: `emails:read`, `emails:all`, `all:read`, `all:all`.", "operationId": "emails_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDetailApiDto" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "413": { "description": "The message is too large to return its body inline. Its `snippet` is still available from the list, and the message can be opened in the dashboard.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "body_too_large", "message": "The message is too large to return its body inline.", "status": 413, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } }, "503": { "description": "A dependency is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "api_error", "code": "upstream_unavailable", "message": "A dependency is temporarily unavailable.", "status": 503, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get an email", "tags": [ "Emails" ] } }, "/v1/emails/{id}/reply": { "post": { "description": "Reply within the email's conversation. It is sent from the mailbox that owns the thread to the other party – you supply only the body (plus optional cc/bcc, which are blocklist-checked).\n\nRequires one of the following scopes: `emails:send`, `emails:all`, `all:all`.", "operationId": "emails_reply", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`.", "required": false, "schema": { "type": "string", "maxLength": 255, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyEmailApiDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "402": { "description": "A plan limit was reached - top up or upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "plan_limit_exceeded", "message": "A plan limit was reached.", "status": 402, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "409": { "description": "The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with an existing resource.", "status": 409, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "422": { "description": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "status": 422, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } }, "503": { "description": "A dependency is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "api_error", "code": "upstream_unavailable", "message": "A dependency is temporarily unavailable.", "status": 503, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Reply to an email", "tags": [ "Emails" ] } }, "/v1/emails/{id}/forward": { "post": { "description": "Forward an email to recipients you choose. It is sent from the mailbox that owns the thread, with the original quoted below your note; all recipients are blocklist-checked.\n\nRequires one of the following scopes: `emails:send`, `emails:all`, `all:all`.", "operationId": "emails_forward", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`.", "required": false, "schema": { "type": "string", "maxLength": 255, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForwardEmailApiDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "402": { "description": "A plan limit was reached - top up or upgrade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "plan_limit_exceeded", "message": "A plan limit was reached.", "status": 402, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "409": { "description": "The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with an existing resource.", "status": 409, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "422": { "description": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "status": 422, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } }, "503": { "description": "A dependency is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "api_error", "code": "upstream_unavailable", "message": "A dependency is temporarily unavailable.", "status": 503, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Forward an email", "tags": [ "Emails" ] } }, "/v1/threads/{id}/read": { "post": { "description": "Mark every email in a conversation as read in one call. Read state lives on the conversation, not the individual email - this is the one call that clears it.\n\nRequires one of the following scopes: `emails:write`, `emails:all`, `all:all`.", "operationId": "emails_markThreadRead", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Opaque conversation identifier, exactly as returned in `threadId`. Do not construct or parse it.", "schema": { "example": "13a265fd-f0f2-b1d1-d6fc-154e483183e7", "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional. A unique key you generate (max 255 chars, such as a UUID) that makes this request safe to retry. Retrying with the same key replays the original response instead of repeating the operation. Reusing a key with a different body returns `422`.", "required": false, "schema": { "type": "string", "maxLength": 255, "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkThreadReadApiResponseDto" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "409": { "description": "The request conflicts with current state - e.g. a request with the same Idempotency-Key is still being processed, or the operation partially applied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "conflict", "message": "The request conflicts with an existing resource.", "status": 409, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "422": { "description": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "idempotency_key_reused", "message": "The Idempotency-Key was already used with a different request body. Use a new key for a new operation.", "status": 422, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Mark a conversation read", "tags": [ "Emails" ] } }, "/v1/campaigns/analytics/overview": { "get": { "description": "Engagement rolled up across every campaign in the workspace, plus the highest-volume campaigns. Use it for a top-level dashboard; drill into a campaign for detail.\n\nRequires one of the following scopes: `metrics:read`, `all:read`, `all:all`.", "operationId": "analytics_getWorkspaceOverview", "parameters": [ { "name": "startDate", "required": false, "in": "query", "description": "Start of the reporting window (ISO-8601). ⚠️ Reporting is by whole calendar day in your workspace timezone – the time component is ignored, so this date counts from the START of that day.", "schema": { "example": "2026-06-01T00:00:00Z", "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "End of the reporting window (ISO-8601). Defaults to now. ⚠️ Inclusive and by whole calendar day (time component ignored) – this counts through the END of that day in your workspace timezone.", "schema": { "example": "2026-06-30T23:59:59Z", "type": "string" } }, { "name": "excludeOOO", "required": false, "in": "query", "description": "Exclude out-of-office auto-replies from reply counts and reply rate. Mirrors the dashboard toggle.", "schema": { "default": false, "example": true, "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAnalyticsApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Workspace analytics roll-up", "tags": [ "Analytics" ] } }, "/v1/campaigns/{id}/analytics/timeseries": { "get": { "description": "One point per interval so you can chart a campaign – this series carries bounces AND unsubscribes, so those rates are chartable without extra calls. Long windows auto-coarsen (day → week → month); the response says which interval it used.\n\nRequires one of the following scopes: `metrics:read`, `all:read`, `all:all`.", "operationId": "analytics_getCampaignTimeseries", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Campaign id.", "schema": { "example": "c1a2b3d4-...", "type": "string" } }, { "name": "startDate", "required": false, "in": "query", "description": "Start of the reporting window (ISO-8601). ⚠️ Reporting is by whole calendar day in your workspace timezone – the time component is ignored, so this date counts from the START of that day.", "schema": { "example": "2026-06-01T00:00:00Z", "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "End of the reporting window (ISO-8601). Defaults to now. ⚠️ Inclusive and by whole calendar day (time component ignored) – this counts through the END of that day in your workspace timezone.", "schema": { "example": "2026-06-30T23:59:59Z", "type": "string" } }, { "name": "excludeOOO", "required": false, "in": "query", "description": "Exclude out-of-office auto-replies from reply counts and reply rate. Mirrors the dashboard toggle.", "schema": { "default": false, "example": true, "type": "boolean" } }, { "name": "interval", "required": false, "in": "query", "description": "Bucket size. Coarser intervals are auto-selected for long windows to keep the series readable.", "schema": { "default": "day", "example": "day", "type": "string", "enum": [ "day", "week", "month" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsTimeseriesApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Campaign analytics over time", "tags": [ "Analytics" ] } }, "/v1/campaigns/{id}/analytics": { "get": { "description": "Aggregate engagement for one campaign. Ask for extra breakdowns with `breakdown=smtp,sequence,bounce` – each is an extra query, so request only what you will read.\n\nRequires one of the following scopes: `metrics:read`, `all:read`, `all:all`.", "operationId": "analytics_getCampaignAnalytics", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Campaign id.", "schema": { "example": "c1a2b3d4-...", "type": "string" } }, { "name": "startDate", "required": false, "in": "query", "description": "Start of the reporting window (ISO-8601). ⚠️ Reporting is by whole calendar day in your workspace timezone – the time component is ignored, so this date counts from the START of that day.", "schema": { "example": "2026-06-01T00:00:00Z", "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "End of the reporting window (ISO-8601). Defaults to now. ⚠️ Inclusive and by whole calendar day (time component ignored) – this counts through the END of that day in your workspace timezone.", "schema": { "example": "2026-06-30T23:59:59Z", "type": "string" } }, { "name": "excludeOOO", "required": false, "in": "query", "description": "Exclude out-of-office auto-replies from reply counts and reply rate. Mirrors the dashboard toggle.", "schema": { "default": false, "example": true, "type": "boolean" } }, { "name": "breakdown", "required": false, "in": "query", "description": "Extra breakdowns to include. Repeat the param or pass a comma-separated list. Each one costs an extra query, so ask only for what you will read.", "schema": { "example": [ "sequence", "bounce" ], "type": "array", "items": { "type": "string", "enum": [ "smtp", "sequence", "bounce" ] } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignAnalyticsApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Campaign analytics", "tags": [ "Analytics" ] } }, "/v1/lead-searches": { "get": { "description": "Cursor-paginate the workspace’s lead searches (newest-first, stable under concurrent changes) for history and to discover ids to poll. In-progress chat drafts are not listed.\n\nRequires one of the following scopes: `leadfinder:read`, `all:read`, `all:all`.", "operationId": "leadSearches_list", "parameters": [ { "name": "cursor", "required": false, "in": "query", "description": "Opaque cursor from a previous response’s `meta.nextCursor`. Omit for the first page. Results are ordered newest-first and stable under concurrent changes.", "schema": { "example": "eyJ0cyI6IjIwMjYtMDctMDJUMDA6MDA6MDAuMDAwWiIsImlkIjoiM2YxYzJiN2UtOWE0ZC00ZTE4LWIyYzEtNmQ4ZjVhMGU3YzkzIn0", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 50, "example": 50, "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadSearchListApiResponseDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "List lead searches", "tags": [ "Lead Finder" ] } }, "/v1/lead-searches/{id}": { "get": { "description": "One search’s status and live progress counters (companies found, companies processed, emails found) – the single target to poll while a run is in flight.\n\nRequires one of the following scopes: `leadfinder:read`, `all:read`, `all:all`.", "operationId": "leadSearches_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "example": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadSearchApiDto" } } } }, "400": { "description": "The request body or parameters failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "One or more fields are invalid.", "status": 400, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "details": [ "name should not be empty" ] } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authentication_error", "code": "unauthenticated", "message": "Missing or invalid API key.", "status": 401, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "403": { "description": "The key lacks a required scope, or the plan does not include API access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "authorization_error", "code": "permission_denied", "message": "This API key is missing the required scope.", "status": 403, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "404": { "description": "The resource does not exist in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "invalid_request_error", "code": "not_found", "message": "Resource not found.", "status": 404, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f" } } } } }, "429": { "description": "Rate limit exceeded - retry after the interval in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorDto" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval in the Retry-After header.", "status": 429, "requestId": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "retryAfter": 30 } } } } } }, "security": [ { "ApiKey": [] } ], "summary": "Get a lead search", "tags": [ "Lead Finder" ] } } }, "info": { "title": "MailBeast Public API", "description": "Task-shaped REST API for campaigns, leads, deliverability, verification and lead discovery. Authenticate with an API key (`Authorization: Bearer mb_live_…`); the workspace is resolved from the key.", "version": "1", "contact": {} }, "tags": [ { "name": "API Keys", "description": "Create, list and delete API keys programmatically." }, { "name": "Campaigns", "description": "Create, configure, launch and monitor email campaigns." }, { "name": "Leads", "description": "Add, read, update and bulk-manage a campaign’s leads." }, { "name": "Workspace", "description": "Read usage, subscription and workspace identity." }, { "name": "Email Accounts", "description": "Connect and manage the sending mailboxes your campaigns send from (SMTP/IMAP or native OAuth)." }, { "name": "Analytics", "description": "Engagement reporting – per campaign, over time, and across the workspace." }, { "name": "Lead Finder", "description": "Discover new companies and leads. List past searches and poll a running search’s progress." } ], "servers": [ { "url": "https://api.mailbeast.ai" } ], "components": { "securitySchemes": { "ApiKey": { "scheme": "bearer", "bearerFormat": "mb_live_…", "type": "http" } }, "schemas": { "ApiErrorBodyDto": { "type": "object", "properties": { "type": { "type": "string", "example": "authorization_error", "description": "Broad error class." }, "code": { "type": "string", "example": "permission_denied", "description": "Stable machine-readable code to switch on." }, "message": { "type": "string", "example": "This API key is missing the required scope." }, "status": { "type": "number", "example": 403 }, "requestId": { "type": "string", "example": "e4f1c0b2-6a3d-4b8e-9f21-0a1b2c3d4e5f", "description": "Correlation id - quote it in support requests." }, "details": { "description": "Field-level validation messages (present on validation errors).", "example": [ "name should not be empty" ], "type": "array", "items": { "type": "string" } }, "retryAfter": { "type": "number", "description": "Seconds to wait before retrying (present on 429 responses).", "example": 30 } }, "required": [ "type", "code", "message", "status", "requestId" ] }, "ApiErrorDto": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiErrorBodyDto" } }, "required": [ "error" ] }, "CreateApiKeyDto": { "type": "object", "properties": { "name": { "type": "string", "example": "CI pipeline", "maxLength": 120 }, "scopes": { "example": [ "campaigns:read", "usage:read" ], "description": "Granted scopes (least-privilege). Must be a subset of the caller.", "type": "array", "items": { "type": "string" } }, "environment": { "type": "string", "enum": [ "live", "test" ], "default": "live" }, "expiresAt": { "type": "string", "format": "date-time", "description": "ISO-8601 expiry; omit for a non-expiring key." } }, "required": [ "name", "scopes" ] }, "ApiKeySummaryDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "5b8e1d90-3c47-4a26-9f01-7ea2c6d5b483" }, "name": { "type": "string", "example": "CI pipeline" }, "keyPrefix": { "type": "string", "example": "mb_live_7Fq2Ka9Lm3Xb0ZpH_••••", "description": "Masked prefix - the full secret is only shown once, at creation." }, "scopes": { "example": [ "campaigns:read", "usage:read" ], "type": "array", "items": { "type": "string" } }, "environment": { "type": "string", "enum": [ "live", "test" ], "example": "live" }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "revokedAt": { "type": "string", "format": "date-time", "nullable": true, "deprecated": true, "description": "Always null: a deleted key is removed, not kept as revoked." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "keyPrefix", "scopes", "environment", "lastUsedAt", "expiresAt", "revokedAt", "createdAt" ] }, "CreateApiKeyResponseDto": { "type": "object", "properties": { "token": { "type": "string", "example": "mb_live_7Fq2Ka9Lm3Xb0ZpH_Ej3VcCSRq0qZHbFbi7GQwD… ", "description": "The full secret token. Store it now - it is never retrievable again." }, "apiKey": { "$ref": "#/components/schemas/ApiKeySummaryDto" } }, "required": [ "token", "apiKey" ] }, "ApiKeyListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeySummaryDto" } } }, "required": [ "data" ] }, "RevokeApiKeyResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] }, "LeadVerificationView": { "type": "object", "properties": { "status": { "type": "string", "nullable": true, "example": "valid" }, "subStatus": { "type": "string", "nullable": true, "example": "email_ok" } } }, "LeadMetricsView": { "type": "object", "properties": { "sent": { "type": "number", "example": 2, "description": "Emails sent to the lead (bounced emails included — they left our servers)." }, "opened": { "type": "number", "example": 1, "description": "Emails the lead opened, counted once per email. Opens are approximate: Apple Mail and security scanners can add or hide opens." }, "clicked": { "type": "number", "example": 0, "description": "Emails in which the lead clicked a tracked link, counted once per email." }, "replied": { "type": "number", "example": 0 } }, "required": [ "sent", "opened", "clicked", "replied" ] }, "LeadSequenceProgressView": { "type": "object", "properties": { "totalSteps": { "type": "number", "example": 3 }, "sentCount": { "type": "number", "example": 1 }, "plannedCount": { "type": "number", "example": 1 }, "failedCount": { "type": "number", "example": 0 }, "nextPlannedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the next step is scheduled to send; null if none pending." } }, "required": [ "totalSteps", "sentCount", "plannedCount", "failedCount" ] }, "LeadApiDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "c9e5b1a3-7f24-4d80-a6b9-2e4f8c0d1a37" }, "email": { "type": "string", "example": "jane@acme.com" }, "firstName": { "type": "string", "nullable": true, "example": "Jane" }, "lastName": { "type": "string", "nullable": true, "example": "Doe" }, "companyName": { "type": "string", "nullable": true, "example": "Acme Inc" }, "jobTitle": { "type": "string", "nullable": true, "example": "VP Sales" }, "website": { "type": "string", "nullable": true, "example": "https://acme.com" }, "linkedinProfile": { "type": "string", "nullable": true, "example": "https://www.linkedin.com/in/janedoe" }, "location": { "type": "string", "nullable": true, "example": "New York, US" }, "tags": { "example": [ "vip", "q4" ], "type": "array", "items": { "type": "string" } }, "customFields": { "type": "object", "additionalProperties": true, "example": { "industry": "SaaS" } }, "status": { "type": "string", "enum": [ "not_contacted", "scheduled", "email_sent", "failed", "skipped", "lead_replied_interested", "lead_replied_meeting_request", "lead_replied_out_of_office", "lead_replied_bounce", "lead_replied_wrong_person", "lead_replied_not_interested", "lead_replied_unsubscribed", "lead_replied_uncategorized", "lead_converted", "lead_lost", "blacklisted" ], "example": "not_contacted" }, "verification": { "$ref": "#/components/schemas/LeadVerificationView" }, "provider": { "type": "string", "nullable": true, "example": "google" }, "metrics": { "$ref": "#/components/schemas/LeadMetricsView" }, "sequenceProgress": { "description": "Live sequence progress - included on the single-lead detail view.", "allOf": [ { "$ref": "#/components/schemas/LeadSequenceProgressView" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "lastContactedAt": { "type": "string", "format": "date-time", "nullable": true }, "lastRepliedAt": { "type": "string", "format": "date-time", "nullable": true }, "lastOpenedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Latest of the per-email first opens: when the lead first opened the newest email it opened. Re-opening an email does not move it; null if no email was opened." }, "lastClickedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Latest of the per-email first clicks: when the lead first clicked a tracked link in the newest email it clicked. Repeat clicks do not move it; null if no tracked link was clicked." } }, "required": [ "id", "email", "tags", "customFields", "status", "verification", "metrics", "createdAt" ] }, "LeadListMetaDto": { "type": "object", "properties": { "hasMore": { "type": "boolean", "example": true, "description": "Whether more leads are available after this page." }, "nextCursor": { "type": "string", "nullable": true, "description": "Pass as `?cursor=` to fetch the next page; null when `hasMore` is false.", "example": "eyJ0cyI6IjIwMjYtMDctMDJUMDA6MDA6MDAuMDAwWiIsImlkIjoiM2YxYzJiN2UtOWE0ZC00ZTE4LWIyYzEtNmQ4ZjVhMGU3YzkzIn0" } }, "required": [ "hasMore" ] }, "LeadListApiResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeadApiDto" } }, "meta": { "$ref": "#/components/schemas/LeadListMetaDto" } }, "required": [ "data", "meta" ] }, "LeadInputApiDto": { "type": "object", "properties": { "email": { "type": "string", "example": "jane@acme.com", "maxLength": 254, "description": "Lead email. Only structural validation here (a non-empty string within the length cap) - a malformed address is NOT a request-level 400 but a non-fatal row counted in `summary.invalid`, so one bad address never rejects the whole batch." }, "firstName": { "type": "string", "example": "Jane", "maxLength": 128 }, "lastName": { "type": "string", "example": "Doe", "maxLength": 128 }, "companyName": { "type": "string", "example": "Acme Inc", "maxLength": 256 }, "jobTitle": { "type": "string", "example": "VP Sales", "maxLength": 128 }, "website": { "type": "string", "example": "https://acme.com", "maxLength": 512 }, "linkedinProfile": { "type": "string", "example": "https://linkedin.com/in/jane", "maxLength": 512 }, "location": { "type": "string", "example": "New York, US", "maxLength": 128 }, "tags": { "example": [ "vip", "q4" ], "type": "array", "items": { "type": "string" } }, "customFields": { "type": "object", "additionalProperties": true, "description": "Custom fields - a flat map of string/number/boolean values. Each key must be lowercase letters, digits and underscores, starting with a letter, up to 64 characters (e.g. `fund_manager`); a key outside that form is rejected. The number of fields per campaign is capped, and each value is length-limited.", "example": { "industry": "SaaS", "employees": 120 } }, "customFieldLabels": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Display labels for custom-field columns (canonical slug → label). Applied only when a field is first defined on the campaign.", "example": { "fund_manager": "Fund Manager" } }, "customFieldTypes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Data types for custom-field columns (canonical slug → text | url | number | date | image). Applied only when first defined.", "example": { "logo_url": "image" } } }, "required": [ "email" ] }, "AddLeadsApiDto": { "type": "object", "properties": { "leads": { "minItems": 1, "maxItems": 100, "description": "Leads to add (1-100). Each is deduplicated by email within the campaign and provider-detected. Send one element to add a single lead.", "type": "array", "items": { "$ref": "#/components/schemas/LeadInputApiDto" } } }, "required": [ "leads" ] }, "AddLeadsSummaryDto": { "type": "object", "properties": { "submitted": { "type": "number", "example": 3, "description": "Leads submitted in the request." }, "created": { "type": "number", "example": 2, "description": "New leads created." }, "duplicates": { "type": "number", "example": 1, "description": "Skipped as duplicates (already in the campaign)." }, "invalid": { "type": "number", "example": 0, "description": "Rejected (invalid or unprocessable)." } }, "required": [ "submitted", "created", "duplicates", "invalid" ] }, "AddLeadsApiResponseDto": { "type": "object", "properties": { "summary": { "$ref": "#/components/schemas/AddLeadsSummaryDto" }, "leads": { "description": "The leads that were created.", "type": "array", "items": { "$ref": "#/components/schemas/LeadApiDto" } } }, "required": [ "summary", "leads" ] }, "UpdateLeadApiDto": { "type": "object", "properties": { "email": { "type": "string", "example": "jane.new@acme.com", "maxLength": 254, "description": "The email can only be changed while the lead has not been contacted yet." }, "firstName": { "type": "string", "maxLength": 128, "example": "Jane" }, "lastName": { "type": "string", "maxLength": 128, "example": "Doe" }, "companyName": { "type": "string", "maxLength": 256, "example": "Acme Inc." }, "jobTitle": { "type": "string", "maxLength": 128, "example": "Head of Growth" }, "website": { "type": "string", "maxLength": 512, "example": "https://acme.com" }, "linkedinProfile": { "type": "string", "maxLength": 512, "example": "https://www.linkedin.com/in/janedoe" }, "location": { "type": "string", "maxLength": 128, "example": "Berlin, Germany" }, "tags": { "example": [ "vip", "q4" ], "type": "array", "items": { "type": "string" } }, "customFields": { "type": "object", "additionalProperties": true, "description": "Custom fields - each key must be lowercase letters, digits and underscores, starting with a letter, up to 64 characters (e.g. `fund_manager`); a key outside that form is rejected. The number of fields per campaign is capped, and each value is length-limited." }, "customFieldLabels": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Display labels for custom-field columns (applied on first definition)." }, "customFieldTypes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Data types for custom-field columns (text | url | number | date | image; applied on first definition)." }, "status": { "type": "string", "enum": [ "lead_replied_interested", "lead_replied_meeting_request", "lead_replied_out_of_office", "lead_replied_wrong_person", "lead_replied_not_interested", "lead_replied_unsubscribed", "lead_replied_uncategorized", "lead_converted", "lead_lost", "blacklisted" ], "description": "Only user-settable statuses are allowed; platform-managed ones such as `email_sent` or `scheduled` are rejected. Reply-based statuses (`lead_replied_*`, `lead_converted`) require the lead to have already replied. `lead_lost` and `blacklisted` can be set at any time." } } }, "DeleteLeadApiResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "retentionDays": { "type": "number", "example": 30, "description": "For soft-deleted leads, days before permanent purge." } }, "required": [ "success" ] }, "MutateLeadsFilterApiDto": { "type": "object", "properties": { "search": { "type": "string", "example": "acme", "description": "Match on email / first name / last name / company." }, "status": { "type": "string", "enum": [ "not_contacted", "scheduled", "email_sent", "failed", "skipped", "lead_replied_interested", "lead_replied_meeting_request", "lead_replied_out_of_office", "lead_replied_bounce", "lead_replied_wrong_person", "lead_replied_not_interested", "lead_replied_unsubscribed", "lead_replied_uncategorized", "lead_converted", "lead_lost", "blacklisted" ] }, "tags": { "example": [ "vip", "q4" ], "type": "array", "items": { "type": "string" } } } }, "MutateLeadsApiDto": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "set_status", "add_tags", "remove_tags", "delete" ] }, "ids": { "maxItems": 1000, "description": "Target lead ids. Required for every operation except a filter-based `delete`.", "example": [ "c9e5b1a3-7f24-4d80-a6b9-2e4f8c0d1a37", "d1a8f4c6-2b93-4e70-8c15-9f0e3a7d6b52" ], "type": "array", "items": { "type": "string" } }, "filter": { "description": "Select targets by filter instead of ids - supported ONLY for `delete`, and must contain at least one condition (an empty filter is rejected).", "allOf": [ { "$ref": "#/components/schemas/MutateLeadsFilterApiDto" } ] }, "all": { "type": "boolean", "description": "Delete EVERY lead in the campaign. Only valid for `delete`, and mutually exclusive with `ids` / `filter`. Required as an explicit opt-in for mass deletion - an empty `filter` will NOT delete all.", "example": false }, "status": { "type": "string", "enum": [ "lead_replied_interested", "lead_replied_meeting_request", "lead_replied_out_of_office", "lead_replied_wrong_person", "lead_replied_not_interested", "lead_replied_unsubscribed", "lead_replied_uncategorized", "lead_converted", "lead_lost", "blacklisted" ], "description": "Required for `set_status`. Only user-settable statuses are allowed; platform-managed ones such as `email_sent` or `scheduled` are rejected. Reply-based statuses (`lead_replied_*`, `lead_converted`) require the lead to have already replied. `lead_lost` and `blacklisted` can be set at any time." }, "tags": { "description": "Required for `add_tags` / `remove_tags`.", "example": [ "vip", "q4" ], "type": "array", "items": { "type": "string" } } }, "required": [ "operation" ] }, "MutateLeadsApiResponseDto": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "set_status", "add_tags", "remove_tags", "delete" ] }, "affected": { "type": "number", "example": 42, "description": "Number of leads successfully affected." }, "failed": { "type": "number", "example": 0, "description": "Number of leads that could not be processed." }, "errors": { "description": "Per-lead error messages, if any.", "example": [ "2 lead(s) not found in this campaign" ], "type": "array", "items": { "type": "string" } } }, "required": [ "operation", "affected", "failed" ] }, "LeadSearchResultApiDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "c9e5b1a3-7f24-4d80-a6b9-2e4f8c0d1a37" }, "email": { "type": "string", "example": "jane@acme.com" }, "firstName": { "type": "string", "nullable": true, "example": "Jane" }, "lastName": { "type": "string", "nullable": true, "example": "Doe" }, "campaignId": { "type": "string", "format": "uuid", "description": "The campaign this lead belongs to.", "example": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60" }, "campaignName": { "type": "string", "example": "Q4 Product Launch Outreach" } }, "required": [ "id", "email", "campaignId", "campaignName" ] }, "LeadSearchApiResponseDto": { "type": "object", "properties": { "data": { "description": "Up to 10 matches; one row per campaign the email appears in.", "type": "array", "items": { "$ref": "#/components/schemas/LeadSearchResultApiDto" } } }, "required": [ "data" ] }, "ScheduleIntervalApiDto": { "type": "object", "properties": { "day": { "type": "integer", "example": 1, "minimum": 1, "maximum": 7, "description": "Day of week, 1=Monday … 7=Sunday." }, "startMinutes": { "type": "integer", "example": 570, "minimum": 0, "maximum": 1410, "description": "Window start, minutes from midnight in the campaign timezone (570 = 09:30). Multiple of 30." }, "endMinutes": { "type": "integer", "example": 1050, "minimum": 30, "maximum": 1440, "description": "Window end, minutes from midnight (1050 = 17:30; 1440 = midnight). Multiple of 30, at least 30 minutes after the start." }, "enabled": { "type": "boolean", "example": true, "default": true, "description": "Disabled windows are kept but not used." } }, "required": [ "day", "startMinutes", "endMinutes" ] }, "CampaignScheduleApiDto": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "simple", "advanced" ], "example": "advanced", "description": "`simple` — one window (`sendingDays` + `sendingMinutesStart/End`) for all days. `advanced` — per-day windows from `intervals`. Passing `intervals` implies `advanced`." }, "intervals": { "description": "Advanced schedule: sending windows per day (up to 50; windows of one day must not overlap; minutes in 30-minute steps). REPLACES all existing windows. Days without an enabled window do not send.", "type": "array", "items": { "$ref": "#/components/schemas/ScheduleIntervalApiDto" } }, "timezone": { "type": "string", "example": "America/New_York", "description": "IANA timezone. Defaults to UTC." }, "sendingDays": { "example": [ 1, 2, 3, 4, 5 ], "description": "Sending days, 1=Monday … 7=Sunday.", "type": "array", "items": { "type": "integer" } }, "sendingMinutesStart": { "type": "integer", "example": 540, "minimum": 0, "maximum": 1439, "description": "Send-window start as minutes from midnight (540 = 09:00)." }, "sendingMinutesEnd": { "type": "integer", "example": 1020, "minimum": 0, "maximum": 1439, "description": "Send-window end as minutes from midnight (1020 = 17:00)." }, "dailyLimit": { "type": "integer", "example": 50, "minimum": 0, "maximum": 10000, "description": "Maximum emails per day for the campaign." }, "startDate": { "type": "string", "format": "date-time", "description": "ISO-8601 start. Omit to start as soon as the campaign is launched (defaults to the creation time)." }, "endDate": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO-8601 end: the campaign sends until the end of that day (campaign timezone), then completes. Omit to run indefinitely; on update, `null` removes the end date." } } }, "CampaignSettingsApiDto": { "type": "object", "properties": { "trackOpens": { "type": "boolean", "example": true, "description": "Track email opens. Not available with `sendAsTextOnly` (`true` while it is on is a 400)." }, "trackClicks": { "type": "boolean", "example": true, "description": "Track link clicks. Not available with `sendAsTextOnly` (`true` while it is on is a 400)." }, "sendAsTextOnly": { "type": "boolean", "example": false, "description": "Send plain-text only (no HTML part). Turning it on turns `sendFirstAsText`, `trackOpens`, `trackClicks` and `unsubscribeLinkBody` off - a plain-text email has no pixel, tracked links or body link." }, "stopOnReply": { "type": "boolean", "example": true, "description": "Stop follow-ups to a lead once they reply." }, "useAllAccounts": { "type": "boolean", "example": false, "description": "Send from every connected mailbox of the workspace (`true`, the default for a new campaign), or only from the mailboxes in `accounts` (`false` — then `accounts` must hold at least one)." }, "stopOnBounce": { "type": "boolean", "example": true, "description": "Stop sending to a lead whose email hard-bounced (the address does not exist). Soft bounces do not stop it. Default `true`." }, "stopCompanyOnReply": { "type": "boolean", "example": true, "description": "When a lead replies, stop the sequence for every other lead of the same company email domain (someone@acme.com replies → all other @acme.com leads stop). Public domains such as gmail.com or outlook.com are never matched. Default `true`." }, "highBounceAutoProtection": { "type": "boolean", "example": false, "description": "Pause the campaign automatically when its hard-bounce rate over the last 24 hours goes above 5%, to protect the sending mailboxes. Default `false`." }, "skipInvalidEmails": { "type": "boolean", "example": true, "description": "Skip leads whose email verification came back `invalid` (the address does not exist). Default `true`." }, "skipUnknownEmails": { "type": "boolean", "example": true, "description": "Skip leads whose email verification came back `unknown` (the mail server gave no clear answer). Default `true`." }, "skipRiskyEmails": { "type": "boolean", "example": false, "description": "Skip leads whose email verification came back `risky` (catch-all / accept-all domain). Worth turning on for large lists: these addresses bounce far more often. Default `false`." }, "sendFirstAsText": { "type": "boolean", "example": false, "description": "Send the first step as plain text and the follow-ups as HTML. The first email is then not tracked and has no body unsubscribe link (the `List-Unsubscribe` header still applies). Cannot be combined with `sendAsTextOnly`: turning one on turns the other off (both `true` in one request is a 400). Default `false`." }, "emailProviderMatching": { "type": "boolean", "example": true, "description": "Prefer a sending mailbox on the same provider as the lead (Google to Google, Outlook to Outlook) when the campaign has one. Default `false`." }, "unsubscribeLinkHeader": { "type": "boolean", "example": true, "description": "Add the one-click `List-Unsubscribe` header (RFC 8058) to every email. Whether the mail client shows an unsubscribe button is up to the provider. Default `false`." }, "unsubscribeLinkBody": { "type": "boolean", "example": false, "description": "Add an unsubscribe link at the bottom of the email body. Not available with `sendAsTextOnly` (a plain-text-only email gets no link): turning `sendAsTextOnly` on turns this off, and `true` while it is on is a 400. Default `false`." }, "autoBlacklistOnUnsubscribe": { "type": "boolean", "example": false, "description": "Also add a lead who unsubscribes to the workspace blacklist, so no campaign emails them again. Without it, unsubscribing stops only this campaign. Default `false`." }, "newLeadsRatio": { "type": "integer", "example": 80, "minimum": 0, "maximum": 100, "description": "Percent of the daily sending that goes to first emails for new leads; the rest goes to follow-up steps. `0` sends follow-ups only, no new lead is contacted. Default `80`." }, "abTestingOptimization": { "type": "boolean", "example": false, "description": "A/B auto-optimization: once every active variant of a step has at least 1000 sends, keep the variant with the best reply rate and switch the others off. Only matters for steps with several `variants`. Default `false`." }, "keepActiveWhenNoLeads": { "type": "boolean", "example": true, "description": "Keep the campaign active when it runs out of leads; new leads added later are scheduled automatically. Default false. With `false`, the campaign completes once every lead has received every step. `schedule.endDate` still completes the campaign either way." }, "hubspotSyncEnabled": { "type": "boolean", "example": true, "description": "Let the recurring HubSpot sync add new contacts to this campaign. Only matters when HubSpot is connected and a HubSpot segment is imported into this campaign. Default `true`." } } }, "CampaignSequenceVariantApiDto": { "type": "object", "properties": { "subject": { "type": "string", "example": "Quick question about {{company_name}}", "maxLength": 500, "description": "Email subject. Merge tags (snake_case): {{first_name}}, {{last_name}}, {{full_name}}, {{email}}, {{company_name}}, {{job_title}}, {{website}}, {{linkedin_profile}}, {{location}}, custom fields as {{custom_}}, sender {{senderFirstName}} / {{senderLastName}} / {{senderFullName}}. No spaces inside the braces. Unknown tags render as empty text." }, "body": { "type": "string", "example": "

Hi {{first_name}}, …

", "description": "HTML body. Same merge tags as the subject, e.g. {{first_name}}, {{company_name}}, {{custom_}}." }, "isActive": { "type": "boolean", "example": true, "default": true, "description": "A switched-off variant is kept but not sent. At least one variant of each step must stay on. Omitted = on: when sending variants back, pass `isActive` as the campaign shows it." } }, "required": [ "subject", "body" ] }, "CampaignSequenceStepApiDto": { "type": "object", "properties": { "subject": { "type": "string", "example": "Quick question about {{company_name}}", "maxLength": 500, "description": "Email subject. Merge tags (snake_case): {{first_name}}, {{last_name}}, {{full_name}}, {{email}}, {{company_name}}, {{job_title}}, {{website}}, {{linkedin_profile}}, {{location}}, custom fields as {{custom_}}, sender {{senderFirstName}} / {{senderLastName}} / {{senderFullName}}. No spaces inside the braces. Unknown tags render as empty text. Required unless you pass `variants`." }, "body": { "type": "string", "example": "

Hi {{first_name}}, …

", "description": "HTML body. Same merge tags as the subject, e.g. {{first_name}}, {{company_name}}, {{custom_}}. Required unless you pass `variants`." }, "variants": { "minItems": 1, "maxItems": 5, "description": "A/B variants of this step, instead of `subject` + `body`: up to 5, lettered A, B, C… in order. Leads are split evenly between the active ones. Pass either `variants` or `subject` + `body`, not both - a step read from GET also shows variant A as `subject` + `body`; leave those out when sending `variants`.", "type": "array", "items": { "$ref": "#/components/schemas/CampaignSequenceVariantApiDto" } }, "delayDays": { "type": "integer", "example": 0, "minimum": 0, "maximum": 365, "description": "Days to wait before this step (0 for the first email)." }, "delayHours": { "type": "integer", "example": 0, "minimum": 0, "maximum": 23, "description": "Additional hours to wait before this step." } } }, "CreateCampaignApiDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Q4 Product Launch Outreach", "maxLength": 255 }, "schedule": { "$ref": "#/components/schemas/CampaignScheduleApiDto" }, "settings": { "$ref": "#/components/schemas/CampaignSettingsApiDto" }, "sequence": { "minItems": 1, "description": "Inline email sequence steps, in send order. Omit for no sequence; when supplied it must have at least one step.", "type": "array", "items": { "$ref": "#/components/schemas/CampaignSequenceStepApiDto" } }, "accounts": { "maxItems": 100, "description": "SMTP account ids the campaign sends from when `settings.useAllAccounts` is `false`. While `useAllAccounts` is `true` (the default) the campaign sends from every connected mailbox and this list does not limit it.", "example": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "array", "items": { "type": "string", "format": "uuid" } }, "tags": { "maxItems": 50, "description": "Campaign tag ids to put on the campaign. Read the ids from `tags[]` on any campaign; tags themselves are created in the dashboard. Mailbox tag ids are a different dictionary and are rejected.", "example": [ "5c9b1e77-2f4a-4c31-9d8e-1a2b3c4d5e6f" ], "type": "array", "items": { "type": "string", "format": "uuid" } }, "leads": { "description": "Lead emails to add. The response summarizes how many were added. Up to 1000. A malformed address is NOT a request-level 400 - it is counted in the leads summary’s `invalid`, so one bad entry never rejects the create.", "example": [ "jane@acme.com" ], "type": "array", "items": { "type": "string" } }, "launch": { "type": "boolean", "example": false, "description": "Start sending immediately after the campaign is configured. Requires the `campaigns:lifecycle` scope in addition to `campaigns:write`." } }, "required": [ "name" ] }, "ScheduleIntervalView": { "type": "object", "properties": { "day": { "type": "number", "example": 1, "description": "1=Monday … 7=Sunday." }, "startMinutes": { "type": "number", "example": 570, "description": "Minutes from midnight." }, "endMinutes": { "type": "number", "example": 1050, "description": "Minutes from midnight (1440 = midnight)." }, "enabled": { "type": "boolean", "example": true } }, "required": [ "day", "startMinutes", "endMinutes", "enabled" ] }, "CampaignScheduleView": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "simple", "advanced" ], "example": "simple", "description": "Which schedule is in effect. `advanced` → `intervals` decide when it sends and `sendingDays` / `sendingMinutesStart/End` are ignored." }, "intervals": { "description": "Per-day windows of the advanced schedule (kept even while `mode` is `simple`).", "type": "array", "items": { "$ref": "#/components/schemas/ScheduleIntervalView" } }, "timezone": { "type": "string", "example": "America/New_York" }, "sendingDays": { "example": [ 1, 2, 3, 4, 5 ], "type": "array", "items": { "type": "number" } }, "sendingMinutesStart": { "type": "number", "example": 540, "description": "Minutes from midnight." }, "sendingMinutesEnd": { "type": "number", "example": 1020, "description": "Minutes from midnight." }, "dailyLimit": { "type": "number", "example": 50 }, "startDate": { "type": "string", "format": "date-time", "nullable": true }, "endDate": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "mode", "intervals", "timezone", "sendingMinutesStart", "sendingMinutesEnd", "dailyLimit" ] }, "CampaignSettingsView": { "type": "object", "properties": { "trackOpens": { "type": "boolean", "example": true }, "trackClicks": { "type": "boolean", "example": true }, "sendAsTextOnly": { "type": "boolean", "example": false }, "stopOnReply": { "type": "boolean", "example": true }, "useAllAccounts": { "type": "boolean", "example": false, "description": "Sends from every connected mailbox of the workspace (`true`) or only from `accounts` (`false`)." }, "stopOnBounce": { "type": "boolean", "example": true, "description": "Stop sending to a lead whose email hard-bounced." }, "stopCompanyOnReply": { "type": "boolean", "example": true, "description": "A reply stops the sequence for every lead of the same company email domain." }, "highBounceAutoProtection": { "type": "boolean", "example": false, "description": "Auto-pause when the 24-hour hard-bounce rate goes above 5%." }, "skipInvalidEmails": { "type": "boolean", "example": true, "description": "Skip leads whose email verification is `invalid`." }, "skipUnknownEmails": { "type": "boolean", "example": true, "description": "Skip leads whose email verification is `unknown`." }, "skipRiskyEmails": { "type": "boolean", "example": false, "description": "Skip leads whose email verification is `risky` (catch-all)." }, "sendFirstAsText": { "type": "boolean", "example": false, "description": "First step as plain text, follow-ups as HTML." }, "emailProviderMatching": { "type": "boolean", "example": true, "description": "Prefer a sending mailbox on the same provider as the lead." }, "unsubscribeLinkHeader": { "type": "boolean", "example": true, "description": "One-click `List-Unsubscribe` header (RFC 8058)." }, "unsubscribeLinkBody": { "type": "boolean", "example": false, "description": "Unsubscribe link at the bottom of the email body." }, "autoBlacklistOnUnsubscribe": { "type": "boolean", "example": false, "description": "Leads who unsubscribe also go to the workspace blacklist." }, "newLeadsRatio": { "type": "number", "example": 80, "description": "Percent of daily sending for first emails to new leads; the rest is follow-ups." }, "abTestingOptimization": { "type": "boolean", "example": false, "description": "A/B auto-optimization: keep the best-replying variant of each step." }, "keepActiveWhenNoLeads": { "type": "boolean", "example": false, "description": "true → the campaign stays active when it runs out of leads and schedules new leads as they are added; false → it completes once every lead has received every step." }, "hubspotSyncEnabled": { "type": "boolean", "example": true, "description": "The recurring HubSpot sync may add contacts to this campaign." } }, "required": [ "trackOpens", "trackClicks", "sendAsTextOnly", "stopOnReply", "useAllAccounts", "stopOnBounce", "stopCompanyOnReply", "highBounceAutoProtection", "skipInvalidEmails", "skipUnknownEmails", "skipRiskyEmails", "sendFirstAsText", "emailProviderMatching", "unsubscribeLinkHeader", "unsubscribeLinkBody", "autoBlacklistOnUnsubscribe", "newLeadsRatio", "abTestingOptimization", "keepActiveWhenNoLeads", "hubspotSyncEnabled" ] }, "CampaignMetricsView": { "type": "object", "properties": { "leadsCount": { "type": "number", "example": 150 }, "sent": { "type": "number", "example": 120, "description": "Emails sent." }, "opens": { "type": "number", "example": 90, "description": "Open events." }, "clicks": { "type": "number", "example": 25, "description": "Click events." }, "replies": { "type": "number", "example": 12, "description": "Replies received." } }, "required": [ "leadsCount", "sent", "opens", "clicks", "replies" ] }, "CampaignSequenceVariantView": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "b3f1a2c4-5d6e-4f70-8a9b-0c1d2e3f4a5b", "description": "Variant id. Pass it as `variantId` to POST /v1/campaigns/{id}/test-email." }, "label": { "type": "string", "example": "A", "description": "A/B variant letter." }, "subject": { "type": "string", "example": "Quick question about {{company_name}}" }, "body": { "type": "string", "example": "

Hi {{first_name}}, …

" }, "isActive": { "type": "boolean", "example": true, "description": "Whether this variant is enabled. It is sent only while its step and the campaign are active too. Leads are split evenly between the enabled variants of a step; A/B auto-optimization switches the losing ones off." } }, "required": [ "id", "label", "subject", "body", "isActive" ] }, "CampaignSequenceStepView": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d" }, "subject": { "type": "string", "example": "Quick question about {{company_name}}", "description": "Subject of the first variant (a copy of `variants[0].subject`). Leave it out when you send the step back with `variants`." }, "body": { "type": "string", "example": "

Hi {{first_name}}, …

", "description": "Body of the first variant (a copy of `variants[0].body`). Leave it out when you send the step back with `variants`." }, "delayDays": { "type": "number", "example": 0 }, "delayHours": { "type": "number", "example": 0 }, "variants": { "description": "A/B variants of this step, by letter (A, B, C…). A step written with `subject` + `body` has a single variant `A`.", "type": "array", "items": { "$ref": "#/components/schemas/CampaignSequenceVariantView" } } }, "required": [ "id", "subject", "body", "delayDays", "delayHours", "variants" ] }, "TagApiDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "5c9b1e77-2f4a-4c31-9d8e-1a2b3c4d5e6f" }, "name": { "type": "string", "example": "client-acme" }, "color": { "type": "string", "nullable": true, "example": "#4F46E5", "description": "Hex colour shown in the dashboard." } }, "required": [ "id", "name", "color" ] }, "CampaignApiDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "name": { "type": "string", "example": "Q4 Product Launch Outreach" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "active", "paused", "stopped", "completed", "failed" ], "example": "draft" }, "schedule": { "$ref": "#/components/schemas/CampaignScheduleView" }, "settings": { "$ref": "#/components/schemas/CampaignSettingsView" }, "metrics": { "$ref": "#/components/schemas/CampaignMetricsView" }, "sequence": { "description": "The email sequence steps - included on the detail view (GET /v1/campaigns/:id).", "type": "array", "items": { "$ref": "#/components/schemas/CampaignSequenceStepView" } }, "accounts": { "description": "Attached SMTP account ids - included on the detail view. The campaign sends only from these when `settings.useAllAccounts` is `false`; while it is `true`, from every connected mailbox of the workspace.", "example": [ "3f1c2b7e-9a4d-4e18-b2c1-6d8f5a0e7c93" ], "type": "array", "items": { "type": "string" } }, "tags": { "description": "Tags on this campaign - the same ones the list returns, and the same ids `?tags=` filters by. Create and delete them in the dashboard. Campaign tags are a separate dictionary from mailbox tags, so the ids do not cross over.", "type": "array", "items": { "$ref": "#/components/schemas/TagApiDto" } }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-07-11T08:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-07-11T10:30:00.000Z" } }, "required": [ "id", "name", "status", "schedule", "settings", "metrics", "tags", "createdAt", "updatedAt" ] }, "CampaignLeadsImportSummaryDto": { "type": "object", "properties": { "submitted": { "type": "number", "example": 100, "description": "Emails submitted in the request." }, "created": { "type": "number", "example": 92, "description": "New leads created." }, "duplicates": { "type": "number", "example": 6, "description": "Skipped as duplicates." }, "invalid": { "type": "number", "example": 2, "description": "Rejected as invalid/unparseable." } }, "required": [ "submitted", "created", "duplicates", "invalid" ] }, "CreateCampaignApiResponseDto": { "type": "object", "properties": { "campaign": { "$ref": "#/components/schemas/CampaignApiDto" }, "leads": { "description": "Present only when `leads` were supplied.", "allOf": [ { "$ref": "#/components/schemas/CampaignLeadsImportSummaryDto" } ] }, "launched": { "type": "boolean", "example": false, "description": "Whether the campaign was launched (true only when `launch: true` succeeded)." }, "launchError": { "type": "string", "example": "Campaign is not ready to launch: No leads added. Start it with POST /v1/campaigns/{id}/start.", "description": "Present only when `launch: true` was requested but the campaign could NOT be started. The campaign is still created (as a draft) - fix the issue and start it via the lifecycle endpoint. Absent on success." } }, "required": [ "campaign", "launched" ] }, "CampaignListItemApiDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60" }, "name": { "type": "string", "example": "Q4 Product Launch Outreach" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "active", "paused", "stopped", "completed", "failed" ], "example": "active" }, "leadsCount": { "type": "number", "example": 150 }, "tags": { "description": "Tags on this campaign. Create and delete them in the dashboard - here they are read, and you can filter the list by them with `?tags=`. Campaign tags are a separate dictionary from mailbox tags, so the ids do not cross over.", "type": "array", "items": { "$ref": "#/components/schemas/TagApiDto" } }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "status", "leadsCount", "tags", "createdAt" ] }, "CampaignListMetaDto": { "type": "object", "properties": { "hasMore": { "type": "boolean", "example": true, "description": "Whether more campaigns are available after this page." }, "nextCursor": { "type": "string", "nullable": true, "description": "Pass as `?cursor=` to fetch the next page; null when `hasMore` is false.", "example": "eyJ0cyI6IjIwMjYtMDctMDJUMDA6MDA6MDAuMDAwWiIsImlkIjoiM2YxYzJiN2UtOWE0ZC00ZTE4LWIyYzEtNmQ4ZjVhMGU3YzkzIn0" } }, "required": [ "hasMore" ] }, "CampaignListApiResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignListItemApiDto" } }, "meta": { "$ref": "#/components/schemas/CampaignListMetaDto" } }, "required": [ "data", "meta" ] }, "UpdateCampaignApiDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Q4 Launch (revised)", "maxLength": 255 }, "schedule": { "$ref": "#/components/schemas/CampaignScheduleApiDto" }, "settings": { "$ref": "#/components/schemas/CampaignSettingsApiDto" }, "sequence": { "minItems": 1, "description": "When supplied, REPLACES the full sequence with these steps (at least one). Omit to leave the sequence unchanged. An active campaign's sequence cannot be replaced - pause it first (400, nothing is written).", "type": "array", "items": { "$ref": "#/components/schemas/CampaignSequenceStepApiDto" } }, "accounts": { "maxItems": 100, "description": "When supplied, REPLACES the attached SMTP account set — the mailboxes the campaign sends from when `settings.useAllAccounts` is `false`. While `useAllAccounts` is `true` the campaign sends from every connected mailbox and this list does not limit it.", "example": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "array", "items": { "type": "string", "format": "uuid" } }, "tags": { "maxItems": 50, "description": "When supplied, REPLACES the campaign's tags (`[]` removes them all). Campaign tag ids to put on the campaign. Read the ids from `tags[]` on any campaign; tags themselves are created in the dashboard. Mailbox tag ids are a different dictionary and are rejected.", "example": [ "5c9b1e77-2f4a-4c31-9d8e-1a2b3c4d5e6f" ], "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "DeleteCampaignApiResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] }, "CampaignLifecycleApiResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "active", "paused", "stopped", "completed", "failed" ], "example": "paused" }, "success": { "type": "boolean", "example": true } }, "required": [ "id", "status", "success" ] }, "CampaignStatusApiDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "active", "paused", "stopped", "completed", "failed" ], "example": "active" }, "isWithinSchedule": { "type": "boolean", "example": true, "description": "Whether now is inside the sending window, for any status: within the campaign dates (not before `startDate`, not after the end of the `endDate` day in the campaign timezone) and inside the schedule (simple or advanced). A draft or paused campaign still does not send." }, "nextScheduleOpensAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the campaign can next send (for any status): the next schedule window, or `startDate` itself when it falls inside a window. null when inside a window now, or when no window opens before the end of the `endDate` day." }, "metrics": { "$ref": "#/components/schemas/CampaignMetricsView" } }, "required": [ "id", "status", "isWithinSchedule", "metrics" ] }, "SendTestEmailApiDto": { "type": "object", "properties": { "variantId": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "description": "The step variant to render: `sequence[].variants[].id` from GET /v1/campaigns/{id}." }, "accountId": { "type": "string", "format": "uuid", "example": "3f1c2b7e-9a4d-4e18-b2c1-6d8f5a0e7c93", "description": "The mailbox to send from. It must be one of yours and within its daily limit." }, "recipient": { "type": "string", "example": "you@acme.com", "description": "Where to send the test. A single address. It is refused if the address, or its domain, is on your blacklist." }, "personalization": { "type": "string", "enum": [ "dummy", "lead" ], "example": "dummy", "description": "Where merge variables come from. `lead` uses a real lead, named by `leadId`. `dummy` uses no lead data: lead tags such as {{first_name}} render EMPTY (only sender tags resolve). There is no fallback: `lead` without `leadId` is rejected." }, "leadId": { "type": "string", "format": "uuid", "example": "c9e5b1a3-7f24-4d80-a6b9-2e4f8c0d1a37", "description": "The lead whose data fills the merge variables. Required when `personalization` is `lead`, and must be omitted otherwise." } }, "required": [ "variantId", "accountId", "recipient", "personalization" ] }, "TestEmailApiResponseDto": { "type": "object", "properties": { "sent": { "type": "boolean", "example": true, "description": "The test email was handed to the mail server." }, "messageId": { "type": "string", "nullable": true, "example": "", "description": "RFC 5322 Message-ID assigned by the sending server. `null` if the server did not return one." } }, "required": [ "sent", "messageId" ] }, "PlanUsageLimitDto": { "type": "object", "properties": { "used": { "type": "number", "example": 1240, "description": "Units consumed this period." }, "limit": { "type": "number", "nullable": true, "example": 5000, "description": "The cap, or `null` when unlimited." }, "remaining": { "type": "number", "nullable": true, "example": 3760, "description": "Units left, or `null` when unlimited." }, "isUnlimited": { "type": "boolean", "example": false }, "usagePercentage": { "type": "number", "example": 24.8, "description": "used / limit × 100 (0 when unlimited)." }, "limitType": { "type": "string", "enum": [ "monthly_emails", "active_contacts", "ai_credits", "email_validation" ], "example": "monthly_emails" } }, "required": [ "used", "limit", "remaining", "isUnlimited", "usagePercentage", "limitType" ] }, "EmailOutreachUsageDto": { "type": "object", "properties": { "planName": { "type": "string", "example": "pro", "description": "Your Email Outreach plan." }, "limits": { "description": "The four Email Outreach plan limits.", "type": "array", "items": { "$ref": "#/components/schemas/PlanUsageLimitDto" } } }, "required": [ "planName", "limits" ] }, "LeadFinderCreditsDto": { "type": "object", "properties": { "used": { "type": "number", "example": 1240, "description": "Units consumed this period." }, "limit": { "type": "number", "nullable": true, "example": 5000, "description": "The cap, or `null` when unlimited." }, "remaining": { "type": "number", "nullable": true, "example": 3760, "description": "Units left, or `null` when unlimited." }, "isUnlimited": { "type": "boolean", "example": false }, "usagePercentage": { "type": "number", "example": 24.8, "description": "used / limit × 100 (0 when unlimited)." }, "limitType": { "type": "string", "enum": [ "lead_finder_credits" ], "example": "lead_finder_credits" } }, "required": [ "used", "limit", "remaining", "isUnlimited", "usagePercentage", "limitType" ] }, "LeadFinderUsageDto": { "type": "object", "properties": { "credits": { "description": "Current Lead Finder credit balance.", "allOf": [ { "$ref": "#/components/schemas/LeadFinderCreditsDto" } ] } }, "required": [ "credits" ] }, "UsageResponseDto": { "type": "object", "properties": { "emailOutreach": { "description": "Your Email Outreach plan usage - the four plan limits.", "allOf": [ { "$ref": "#/components/schemas/EmailOutreachUsageDto" } ] }, "leadFinder": { "description": "Your Lead Finder usage - a separate product with its own credit balance.", "allOf": [ { "$ref": "#/components/schemas/LeadFinderUsageDto" } ] } }, "required": [ "emailOutreach", "leadFinder" ] }, "UsageLimitDto": { "type": "object", "properties": { "used": { "type": "number", "example": 1240, "description": "Units consumed this period." }, "limit": { "type": "number", "nullable": true, "example": 5000, "description": "The cap, or `null` when unlimited." }, "remaining": { "type": "number", "nullable": true, "example": 3760, "description": "Units left, or `null` when unlimited." }, "isUnlimited": { "type": "boolean", "example": false }, "usagePercentage": { "type": "number", "example": 24.8, "description": "used / limit × 100 (0 when unlimited)." }, "limitType": { "type": "string", "enum": [ "monthly_emails", "active_contacts", "ai_credits", "email_validation", "lead_finder_credits" ], "example": "monthly_emails" } }, "required": [ "used", "limit", "remaining", "isUnlimited", "usagePercentage", "limitType" ] }, "SubscriptionTrialDto": { "type": "object", "properties": { "isActive": { "type": "boolean", "example": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "daysRemaining": { "type": "number", "example": 5 } }, "required": [ "isActive", "expiresAt", "daysRemaining" ] }, "SubscriptionAddonsDto": { "type": "object", "properties": { "contacts": { "type": "number", "example": 20000, "description": "Extra active-contact capacity." }, "monthlyEmails": { "type": "number", "example": 10000, "description": "Extra monthly-email capacity." }, "aiCredits": { "type": "number", "example": 5000, "description": "Extra AI credits." }, "emailValidation": { "type": "number", "example": 0, "description": "Extra email-verification credits." } }, "required": [ "contacts", "monthlyEmails", "aiCredits", "emailValidation" ] }, "EmailOutreachSubscriptionDto": { "type": "object", "properties": { "planName": { "type": "string", "example": "pro", "description": "Your Email Outreach plan." }, "status": { "type": "string", "enum": [ "active", "on_hold", "inactive" ], "example": "active", "description": "Subscription state: `active`, `on_hold`, or `inactive` (no active subscription - e.g. free plan)." }, "billingInterval": { "type": "string", "nullable": true, "example": "monthly", "description": "`monthly` | `annual` | null." }, "currentPeriodEnd": { "type": "string", "format": "date-time", "nullable": true, "description": "When the current paid period ends - it renews then, or ends if `cancelAtPeriodEnd` is true. Null with no active subscription." }, "cancelAtPeriodEnd": { "type": "boolean", "example": false }, "trial": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/SubscriptionTrialDto" } ] }, "addons": { "nullable": true, "description": "Extra capacity bought as add-ons on this plan (already folded into your /v1/usage limits). Null when there are none.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/SubscriptionAddonsDto" } ] } }, "required": [ "planName", "status", "billingInterval", "currentPeriodEnd", "cancelAtPeriodEnd", "trial", "addons" ] }, "LeadFinderSubscriptionDto": { "type": "object", "properties": { "tier": { "type": "string", "enum": [ "starter", "pro", "max" ], "nullable": true, "example": "pro", "description": "Lead Finder tier, or null if you have no Lead Finder subscription." }, "status": { "type": "string", "nullable": true, "enum": [ "active", "on_hold" ], "example": "active", "description": "`active`, `on_hold`, or null (no Lead Finder subscription)." }, "billingInterval": { "type": "string", "nullable": true, "example": "monthly", "description": "`monthly` | `annual` | null." }, "currentPeriodEnd": { "type": "string", "format": "date-time", "nullable": true, "description": "When the current Lead Finder paid period ends - its own cycle, independent of the Email Outreach plan." }, "cancelAtPeriodEnd": { "type": "boolean", "example": false } }, "required": [ "tier", "status", "billingInterval", "currentPeriodEnd", "cancelAtPeriodEnd" ] }, "SubscriptionResponseDto": { "type": "object", "properties": { "emailOutreach": { "description": "Your Email Outreach subscription - plan, billing cycle, trial, and add-ons.", "allOf": [ { "$ref": "#/components/schemas/EmailOutreachSubscriptionDto" } ] }, "leadFinder": { "nullable": true, "description": "Your separate Lead Finder subscription, or null if you have none.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/LeadFinderSubscriptionDto" } ] } }, "required": [ "emailOutreach", "leadFinder" ] }, "WorkspaceResponseDto": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "The organization resolved from the API key.", "example": "b6fd2c26-df61-467a-bfcf-6228e3f7064e" }, "name": { "type": "string", "example": "Acme Inc" }, "timezone": { "type": "string", "example": "America/New_York", "description": "IANA timezone." } }, "required": [ "organizationId", "name", "timezone" ] }, "AccountTrackingApiDto": { "type": "object", "properties": { "domainId": { "type": "string", "format": "uuid", "example": "9b7d4e53-91a0-4c2f-8a19-5d3e7f6b2c84", "nullable": true, "description": "One of your workspace tracking domains. Attaching one enables open/click tracking for this mailbox. When omitted on connect, the workspace default is assigned; pass `null` for no tracking." } } }, "AccountWarmupApiDto": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": true, "description": "Enroll the mailbox in warmup. Defaults to true on connect." }, "strategy": { "type": "string", "enum": [ "standard", "aggressive", "custom" ], "example": "standard", "description": "`standard` and `aggressive` are fixed profiles (conservative / faster) with their own ramp, cap and reply rate. `custom` is what makes `maxPerDay`, `rampupEnabled`, `dailyRampup`, `randomizer` and `replyRatePercentage` take effect." }, "maxPerDay": { "type": "number", "minimum": 0, "maximum": 30, "example": 15, "description": "Warmup emails per day, up to 30. Separate from `maxEmailsPerDay`, which caps CAMPAIGN sending only. `0` keeps warmup on but sends nothing. While the mailbox is still ramping up this is honoured on `custom` only (the preset strategies use their own cap), but once warmup reaches the steady maintaining stage it is the ceiling for EVERY strategy." }, "replyRatePercentage": { "type": "number", "minimum": 20, "maximum": 80, "example": 35, "description": "Share of warmup emails that get a reply. `custom` strategy only; the presets use their own reply rate." }, "rampupEnabled": { "type": "boolean", "example": true, "description": "Grow the daily volume gradually (by `dailyRampup` each day) instead of sending `maxPerDay` from day one. `custom` strategy only." }, "dailyRampup": { "type": "number", "minimum": 1, "maximum": 10, "example": 1, "description": "Emails added per day while ramping up. Read only when `rampupEnabled` is **true**. With ramp-up off the mailbox sends a flat `maxPerDay` every day and this is ignored. `custom` strategy only." }, "randomizer": { "type": "number", "minimum": 0, "maximum": 50, "example": 0, "description": "Percent of warmup sends randomly skipped each day, so volume is not identical day to day. `custom` strategy only." }, "skipWeekends": { "type": "boolean", "example": false, "description": "Skip Saturdays and Sundays." }, "timezone": { "type": "string", "example": "Europe/London", "description": "IANA timezone the warmup schedule runs in. Defaults to the workspace timezone." }, "trackingEnabled": { "type": "boolean", "example": true, "description": "Track opens on warmup emails." } } }, "CreateAccountApiDto": { "type": "object", "properties": { "emailAddress": { "type": "string", "example": "jane@acme.com", "maxLength": 254 }, "firstName": { "type": "string", "example": "Jane", "maxLength": 128 }, "lastName": { "type": "string", "example": "Doe", "maxLength": 128 }, "displayName": { "type": "string", "example": "Jane Doe", "maxLength": 128, "description": "Display name shown as the sender. Defaults to “First Last”." }, "smtpHost": { "type": "string", "example": "smtp.acme.com", "maxLength": 255 }, "smtpPort": { "type": "number", "example": 587, "minimum": 1, "maximum": 65535 }, "smtpUsername": { "type": "string", "example": "jane@acme.com", "maxLength": 255 }, "smtpPassword": { "type": "string", "maxLength": 1024, "description": "SMTP password. Stored encrypted; never returned.", "example": "your-password" }, "imapHost": { "type": "string", "example": "imap.acme.com", "maxLength": 255 }, "imapPort": { "type": "number", "example": 993, "minimum": 1, "maximum": 65535 }, "imapUsername": { "type": "string", "example": "jane@acme.com", "maxLength": 255 }, "imapPassword": { "type": "string", "maxLength": 1024, "description": "IMAP password. Stored encrypted; never returned.", "example": "your-password" }, "imapAllowInvalidCert": { "type": "boolean", "example": false, "description": "Accept a self-signed IMAP certificate." }, "maxEmailsPerDay": { "type": "number", "example": 30, "minimum": 1, "maximum": 200, "description": "Daily CAMPAIGN send cap for this mailbox. Warmup has its own budget (`warmup.maxPerDay`)." }, "sendingGapMinutes": { "type": "number", "minimum": 1, "maximum": 300, "example": 10, "description": "Minimum minutes between two sends from this mailbox, across all campaigns." }, "campaignSlowRamp": { "type": "boolean", "example": false, "description": "Ramp campaign volume up gradually when the mailbox joins a campaign." }, "signature": { "type": "string", "example": "Best regards,
Jane", "description": "HTML signature appended to outgoing emails. Sanitized on save." }, "bcc": { "type": "string", "maxLength": 254, "example": "archive@acme.com", "description": "BCC every email from this mailbox to this address." }, "replyToAddress": { "type": "string", "maxLength": 254, "example": "replies@acme.com", "description": "Send replies somewhere other than the mailbox address. Omit to reply to the mailbox itself." }, "automationLanguage": { "type": "string", "enum": [ "en", "ar", "bn", "zh", "cs", "da", "nl", "fi", "fr", "de", "el", "he", "hi", "hu", "id", "it", "ja", "ko", "ms", "no", "pl", "pt", "ro", "ru", "es", "sv", "th", "tr", "uk", "vi" ], "example": "en", "description": "ISO 639-1 language for auto-generated content (warmup bodies, replies)." }, "tracking": { "$ref": "#/components/schemas/AccountTrackingApiDto" }, "warmup": { "description": "Warmup config. Omit to accept the defaults (warmup ON).", "allOf": [ { "$ref": "#/components/schemas/AccountWarmupApiDto" } ] } }, "required": [ "emailAddress", "firstName", "lastName", "smtpHost", "smtpPort", "smtpUsername", "smtpPassword", "imapHost", "imapPort", "imapUsername", "imapPassword" ] }, "CreateAccountsApiDto": { "type": "object", "properties": { "accounts": { "minItems": 1, "maxItems": 50, "description": "Mailboxes to connect (1-50). Each is validated and created independently; the response reports which succeeded and which failed (e.g. an email already connected elsewhere).", "type": "array", "items": { "$ref": "#/components/schemas/CreateAccountApiDto" } } }, "required": [ "accounts" ] }, "CreateAccountsSummaryDto": { "type": "object", "properties": { "submitted": { "type": "number", "example": 2 }, "created": { "type": "number", "example": 1 }, "failed": { "type": "number", "example": 1 } }, "required": [ "submitted", "created", "failed" ] }, "AccountWarmupSummaryDto": { "type": "object", "properties": { "enabled": { "type": "boolean", "example": true }, "strategy": { "type": "string", "enum": [ "standard", "aggressive", "custom" ], "example": "standard", "description": "Fixed preset (`standard` / `aggressive`), or `custom` to run on the tuning values below." }, "maxPerDay": { "type": "number", "example": 15, "description": "Warmup emails per day. Separate from the campaign cap. Honoured while ramping up on `custom` only; from the maintaining stage on it caps every strategy." }, "replyRatePercentage": { "type": "number", "example": 35, "description": "`custom` strategy only; the presets use their own reply rate." }, "rampupEnabled": { "type": "boolean", "example": true, "description": "`custom` strategy only." }, "dailyRampup": { "type": "number", "example": 1, "description": "Emails added per day while ramping. Read only when `rampupEnabled` is true. `custom` strategy only." }, "randomizer": { "type": "number", "example": 0, "description": "Percent of warmup sends randomly skipped each day. `custom` strategy only." }, "skipWeekends": { "type": "boolean", "example": false }, "timezone": { "type": "string", "example": "Europe/London" }, "trackingEnabled": { "type": "boolean", "example": true }, "phase": { "type": "string", "nullable": true, "enum": [ "warming_up", "maintaining", "active_with_campaigns" ], "description": "Where the mailbox is in its warmup lifecycle. Null until warmup starts." }, "startedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When warmup began. Null if it never has." }, "poolAccess": { "type": "string", "enum": [ "free", "standard", "premium", "ultra" ], "description": "Quality of the warmup pool this mailbox converses with. Set by your plan, read-only." } }, "required": [ "enabled", "strategy", "maxPerDay", "replyRatePercentage", "rampupEnabled", "dailyRampup", "randomizer", "skipWeekends", "timezone", "trackingEnabled", "phase", "startedAt", "poolAccess" ] }, "AccountTrackingSummaryDto": { "type": "object", "properties": { "domainId": { "type": "string", "nullable": true, "format": "uuid", "description": "Tracking domain in use. Null means opens and clicks are not tracked for this mailbox.", "example": "9d1f7c4a-6e58-4b32-8a07-3c5d9e2f1b46" } }, "required": [ "domainId" ] }, "AccountStatusMessageDto": { "type": "object", "properties": { "code": { "type": "string", "nullable": true, "example": "EENVELOPE", "description": "Transport/protocol class of the failure." }, "command": { "type": "string", "nullable": true, "example": "DATA", "description": "The SMTP command that failed." }, "responseCode": { "type": "number", "nullable": true, "example": 550, "description": "Numeric SMTP status returned by the provider." }, "response": { "type": "string", "nullable": true, "example": "550-5.4.5 Daily user sending limit exceeded.", "description": "The provider’s raw response line." }, "message": { "type": "string", "example": "Daily user sending limit exceeded", "description": "The error text." }, "occurredAt": { "type": "string", "format": "date-time", "description": "When the failure happened." } }, "required": [ "code", "command", "responseCode", "response", "message", "occurredAt" ] }, "AccountSmtpDto": { "type": "object", "properties": { "host": { "type": "string", "nullable": true, "example": "smtp.acme.com" }, "port": { "type": "number", "nullable": true, "example": 587 }, "username": { "type": "string", "nullable": true, "example": "jane@acme.com" } }, "required": [ "host", "port", "username" ] }, "AccountImapDto": { "type": "object", "properties": { "host": { "type": "string", "nullable": true, "example": "imap.acme.com" }, "port": { "type": "number", "nullable": true, "example": 993 }, "username": { "type": "string", "nullable": true, "example": "jane@acme.com" } }, "required": [ "host", "port", "username" ] }, "AccountDnsDto": { "type": "object", "properties": { "mx": { "type": "string", "enum": [ "not_checked", "pending", "in_progress", "verified", "failed", "check_unavailable", "skipped" ] }, "spf": { "type": "string", "enum": [ "not_checked", "pending", "in_progress", "verified", "failed", "check_unavailable", "skipped" ] }, "dkim": { "type": "string", "enum": [ "not_checked", "pending", "in_progress", "verified", "failed", "check_unavailable", "skipped" ] }, "dmarc": { "type": "string", "enum": [ "not_checked", "pending", "in_progress", "verified", "failed", "check_unavailable", "skipped" ] } }, "required": [ "mx", "spf", "dkim", "dmarc" ] }, "AccountVerificationSummaryDto": { "type": "object", "properties": { "overallStatus": { "type": "string", "enum": [ "pending", "verified", "failed" ], "description": "Overall outcome of the mailbox checks." }, "smtp": { "type": "string", "description": "Sending status of the mailbox.", "enum": [ "active", "inactive", "checking", "revoked", "failed" ] }, "imap": { "type": "string", "enum": [ "not_checked", "pending", "in_progress", "verified", "failed", "check_unavailable", "skipped" ], "description": "IMAP connection status." }, "dns": { "$ref": "#/components/schemas/AccountDnsDto" } }, "required": [ "overallStatus", "smtp", "imap", "dns" ] }, "AccountApiDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "3f1c2b7e-9a4d-4e18-b2c1-6d8f5a0e7c93" }, "emailAddress": { "type": "string", "example": "jane@acme.com" }, "firstName": { "type": "string", "nullable": true, "example": "Jane" }, "lastName": { "type": "string", "nullable": true, "example": "Doe" }, "displayName": { "type": "string", "nullable": true, "example": "Jane Doe" }, "provider": { "type": "string", "example": "custom", "description": "How the mailbox is connected: `custom` for any SMTP/IMAP mailbox (including Gmail/Outlook connected with an app password), or `google` / `microsoft` for a native OAuth connection." }, "status": { "type": "string", "enum": [ "active", "inactive", "checking", "revoked", "failed" ], "description": "Current state. `active` - sending. `inactive` - paused by you (or connected but not verified yet); nothing re-activates it on its own, call `resume`. `checking` - being verified. `failed` - we stopped it after repeated failures; see `statusMessage` for the provider’s reason, and `resume` re-checks it. `revoked` - the OAuth grant is gone; reconnect it." }, "maxEmailsPerDay": { "type": "number", "example": 30, "description": "Daily CAMPAIGN send cap. Warmup is budgeted separately (`warmup.maxPerDay`)." }, "sendingGapMinutes": { "type": "number", "example": 10, "description": "Minimum minutes between two sends from this mailbox, across all campaigns." }, "campaignSlowRamp": { "type": "boolean", "example": false, "description": "Ramp campaign volume up gradually when the mailbox joins a campaign." }, "replyToAddress": { "type": "string", "nullable": true, "example": "replies@acme.com", "description": "Where replies are sent, when it differs from the mailbox address." }, "signature": { "type": "string", "nullable": true, "example": "Best regards,
Jane", "description": "HTML signature appended to outgoing emails." }, "bcc": { "type": "string", "nullable": true, "example": "archive@acme.com" }, "automationLanguage": { "type": "string", "example": "en", "description": "ISO 639-1 language for auto-generated content." }, "warmup": { "$ref": "#/components/schemas/AccountWarmupSummaryDto" }, "tracking": { "$ref": "#/components/schemas/AccountTrackingSummaryDto" }, "statusMessage": { "nullable": true, "description": "Why the mailbox last failed, as reported by its provider. Null when it is healthy, and also null when the failure was on our side, since that is not a problem with your mailbox.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AccountStatusMessageDto" } ] }, "tags": { "description": "Tags on this mailbox. Create and delete them in the dashboard - here they are read, and you can filter the list by them with `?tags=`.", "type": "array", "items": { "$ref": "#/components/schemas/TagApiDto" } }, "healthScore": { "type": "number", "example": 98, "description": "Deliverability health score, from 0 to 100." }, "smtp": { "$ref": "#/components/schemas/AccountSmtpDto" }, "imap": { "nullable": true, "description": "Null when no IMAP is configured.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AccountImapDto" } ] }, "verification": { "$ref": "#/components/schemas/AccountVerificationSummaryDto" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "emailAddress", "firstName", "lastName", "displayName", "provider", "status", "maxEmailsPerDay", "sendingGapMinutes", "campaignSlowRamp", "replyToAddress", "signature", "bcc", "automationLanguage", "warmup", "tracking", "statusMessage", "tags", "healthScore", "smtp", "imap", "verification", "createdAt", "updatedAt" ] }, "CreateAccountErrorDto": { "type": "object", "properties": { "index": { "type": "number", "example": 0, "description": "Index of the failing account in the request array." }, "emailAddress": { "type": "string", "example": "jane@acme.com" }, "code": { "type": "string", "enum": [ "mailbox_connected_elsewhere", "mailbox_already_exists", "conflict" ], "example": "mailbox_connected_elsewhere", "description": "Branch on this, not on `error`. `mailbox_connected_elsewhere` - the address is connected in a different workspace; a mailbox can only live in one workspace at a time, so disconnect it there first. `mailbox_already_exists` - it is already connected in this workspace, nothing to do. `conflict` - any other conflict." }, "error": { "type": "string", "example": "This mailbox is already connected to another MailBeast workspace. Disconnect it there before adding it here.", "description": "Human-readable reason, safe to show a user. Wording may change - match on `code` instead." } }, "required": [ "index", "emailAddress", "code", "error" ] }, "CreateAccountsApiResponseDto": { "type": "object", "properties": { "summary": { "$ref": "#/components/schemas/CreateAccountsSummaryDto" }, "accounts": { "description": "The mailboxes that were connected. They start `inactive` and are verified in the background - poll `GET /v1/accounts/{id}` for the outcome.", "type": "array", "items": { "$ref": "#/components/schemas/AccountApiDto" } }, "errors": { "description": "The mailboxes that could not be connected. Each element is independent: the rest of the batch is still created.", "type": "array", "items": { "$ref": "#/components/schemas/CreateAccountErrorDto" } } }, "required": [ "summary", "accounts", "errors" ] }, "AccountListMetaDto": { "type": "object", "properties": { "hasMore": { "type": "boolean", "example": true }, "nextCursor": { "type": "string", "nullable": true, "description": "Pass as `?cursor=` for the next page; `null` on the last page.", "example": "eyJ0cyI6IjIwMjYtMDctMDJUMDA6MDA6MDAuMDAwWiIsImlkIjoiM2YxYzJiN2UtOWE0ZC00ZTE4LWIyYzEtNmQ4ZjVhMGU3YzkzIn0" } }, "required": [ "hasMore", "nextCursor" ] }, "AccountListApiResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccountApiDto" } }, "meta": { "$ref": "#/components/schemas/AccountListMetaDto" } }, "required": [ "data", "meta" ] }, "UpdateAccountApiDto": { "type": "object", "properties": { "firstName": { "type": "string", "maxLength": 128, "example": "Jane" }, "lastName": { "type": "string", "maxLength": 128, "example": "Doe" }, "displayName": { "type": "string", "maxLength": 128, "example": "Jane Doe" }, "maxEmailsPerDay": { "type": "number", "minimum": 1, "maximum": 200, "example": 60, "description": "Daily CAMPAIGN send cap. Warmup has its own budget (`warmup.maxPerDay`)." }, "sendingGapMinutes": { "type": "number", "minimum": 1, "maximum": 300, "example": 10, "description": "Minimum minutes between two sends from this mailbox, across all campaigns." }, "campaignSlowRamp": { "type": "boolean", "example": false }, "signature": { "type": "string", "example": "Best regards,
Jane", "description": "HTML signature. Sanitized on save." }, "bcc": { "type": "string", "maxLength": 254, "example": "archive@acme.com" }, "replyToAddress": { "type": "string", "maxLength": 254, "example": "replies@acme.com", "description": "Pass `\"\"` to clear it and reply to the mailbox address again." }, "automationLanguage": { "type": "string", "enum": [ "en", "ar", "bn", "zh", "cs", "da", "nl", "fi", "fr", "de", "el", "he", "hi", "hu", "id", "it", "ja", "ko", "ms", "no", "pl", "pt", "ro", "ru", "es", "sv", "th", "tr", "uk", "vi" ], "example": "en" }, "tracking": { "$ref": "#/components/schemas/AccountTrackingApiDto" }, "warmup": { "description": "Warmup config. Only the keys you send are changed. Turning `enabled` on for a mailbox that has been paused resumes it where it left off.", "allOf": [ { "$ref": "#/components/schemas/AccountWarmupApiDto" } ] }, "smtpHost": { "type": "string", "maxLength": 255, "example": "smtp.acme.com" }, "smtpPort": { "type": "number", "minimum": 1, "maximum": 65535, "example": 587 }, "smtpUsername": { "type": "string", "maxLength": 255, "example": "jane@acme.com" }, "smtpPassword": { "type": "string", "maxLength": 1024, "example": "your-password" }, "imapHost": { "type": "string", "maxLength": 255, "example": "imap.acme.com" }, "imapPort": { "type": "number", "minimum": 1, "maximum": 65535, "example": 993 }, "imapUsername": { "type": "string", "maxLength": 255, "example": "jane@acme.com" }, "imapPassword": { "type": "string", "maxLength": 1024, "example": "your-password" }, "imapAllowInvalidCert": { "type": "boolean", "example": false } } }, "DeleteAccountApiResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "3f1c2b7e-9a4d-4e18-b2c1-6d8f5a0e7c93" }, "deleted": { "type": "boolean", "example": true } }, "required": [ "id", "deleted" ] }, "BulkAccountPatchApiDto": { "type": "object", "properties": { "displayName": { "type": "string", "maxLength": 128, "example": "Jane Doe" }, "firstName": { "type": "string", "maxLength": 128, "example": "Jane" }, "lastName": { "type": "string", "maxLength": 128, "example": "Doe" }, "maxEmailsPerDay": { "type": "number", "minimum": 1, "maximum": 200, "example": 60 }, "replyToAddress": { "type": "string", "maxLength": 254, "example": "replies@acme.com", "description": "Pass `\"\"` to clear it and reply to each mailbox address again, same as the single PATCH." }, "sendingGapMinutes": { "type": "number", "minimum": 1, "maximum": 300, "example": 10 }, "campaignSlowRamp": { "type": "boolean", "example": false }, "signature": { "type": "string", "example": "Best regards,
Jane" }, "bcc": { "type": "string", "maxLength": 254, "example": "archive@acme.com" }, "automationLanguage": { "type": "string", "enum": [ "en", "ar", "bn", "zh", "cs", "da", "nl", "fi", "fr", "de", "el", "he", "hi", "hu", "id", "it", "ja", "ko", "ms", "no", "pl", "pt", "ro", "ru", "es", "sv", "th", "tr", "uk", "vi" ], "example": "en" }, "tracking": { "$ref": "#/components/schemas/AccountTrackingApiDto" }, "warmup": { "$ref": "#/components/schemas/AccountWarmupApiDto" } } }, "BulkAccountsApiDto": { "type": "object", "properties": { "ids": { "maxItems": 1000, "description": "Target account ids.", "example": [ "3f1c2b7e-9a4d-4e18-b2c1-6d8f5a0e7c93", "8c2f6a19-4b7d-4e53-91a0-5d3e7f6b2c84" ], "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Enable (`active`) or disable (`inactive`) sending across the set. Mutually exclusive with `patch`." }, "patch": { "description": "Settings/limits to apply to every account. Mutually exclusive with `status`.", "allOf": [ { "$ref": "#/components/schemas/BulkAccountPatchApiDto" } ] } }, "required": [ "ids" ] }, "BulkSkippedAccountDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "3f1c2b7e-9a4d-4e18-b2c1-6d8f5a0e7c93", "description": "The id you passed in `ids`, so a skip can always be matched back to the request." }, "email": { "type": "string", "nullable": true, "example": "jane@acme.com", "description": "Null when the id matches no mailbox in your workspace (`status: \"not_found\"`)." }, "status": { "type": "string", "example": "checking" }, "reason": { "type": "string", "example": "Account is being verified." } }, "required": [ "id", "email", "status", "reason" ] }, "BulkAccountsApiResponseDto": { "type": "object", "properties": { "updated": { "type": "number", "example": 5, "description": "Accounts updated." }, "skipped": { "type": "number", "example": 1, "description": "Mailboxes that were not eligible for this change." }, "skippedAccounts": { "type": "array", "items": { "$ref": "#/components/schemas/BulkSkippedAccountDto" } } }, "required": [ "updated", "skipped", "skippedAccounts" ] }, "VerificationCheckDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_checked", "pending", "in_progress", "verified", "failed", "check_unavailable", "skipped" ] }, "error": { "type": "string", "nullable": true, "description": "Failure detail, or null when the check passed.", "example": "No SPF record found" } }, "required": [ "status", "error" ] }, "AccountVerificationApiDto": { "type": "object", "properties": { "overallStatus": { "type": "string", "enum": [ "pending", "verified", "failed" ] }, "smtp": { "$ref": "#/components/schemas/VerificationCheckDto" }, "imap": { "$ref": "#/components/schemas/VerificationCheckDto" }, "dns": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/VerificationCheckDto" }, "description": "DNS checks: `mx`, `spf`, `dkim`, `dmarc`, `a`." }, "lastVerifiedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "overallStatus", "smtp", "imap", "dns", "lastVerifiedAt" ] }, "OAuthInitApiResponseDto": { "type": "object", "properties": { "authorizationUrl": { "type": "string", "description": "Open this consent URL in a browser so the mailbox owner can grant access.", "example": "https://accounts.google.com/o/oauth2/v2/auth?client_id=…&state=…" }, "state": { "type": "string", "description": "Opaque handle. Pass it to the status endpoint to poll the result.", "example": "aB3dEf6hIjKlMnOpQrStUvWxYz0123456789_-AbCdE" }, "expiresInSeconds": { "type": "number", "example": 600, "description": "How long the consent link / state stays valid." } }, "required": [ "authorizationUrl", "state", "expiresInSeconds" ] }, "OAuthStatusApiResponseDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "connected", "failed" ], "description": "`pending` until consent completes, then `connected` (with `accountId`) or `failed`." }, "accountId": { "type": "string", "nullable": true, "description": "The connected account id once `status` is `connected`; otherwise null.", "example": "3f1c2b7e-9a4d-4e18-b2c1-6d8f5a0e7c93" }, "error": { "type": "string", "nullable": true, "description": "Failure reason when `status` is `failed`.", "example": "The mailbox owner denied access." } }, "required": [ "status", "accountId", "error" ] }, "EmailMailboxDto": { "type": "object", "properties": { "id": { "type": "string", "example": "3f1c2b7e-9a4d-4c8e-b1f6-5d2a7e0c3b94" }, "email": { "type": "string", "example": "jane@acme.com" } }, "required": [ "id", "email" ] }, "EmailParticipantDto": { "type": "object", "properties": { "email": { "type": "string", "example": "john@prospect.io" }, "name": { "type": "string", "nullable": true, "example": "John Carter" } }, "required": [ "email", "name" ] }, "EmailApiDto": { "type": "object", "properties": { "id": { "type": "string", "example": "8c5a1e07-2b93-4d6f-a0e8-7c4b9d1f2a36" }, "threadId": { "type": "string", "nullable": true, "example": "13a265fd-f0f2-b1d1-d6fc-154e483183e7", "description": "Conversation this email belongs to. `null` when the email is not part of a conversation. An opaque identifier: pass it back as-is, do not parse or construct it." }, "messageId": { "type": "string", "nullable": true, "example": "", "description": "RFC 5322 Message-ID as set by the sending server." }, "mailbox": { "nullable": true, "description": "The mailbox of yours that sent or received this email.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/EmailMailboxDto" } ] }, "from": { "$ref": "#/components/schemas/EmailParticipantDto" }, "to": { "example": [ "jane@acme.com" ], "type": "array", "items": { "type": "string" } }, "cc": { "example": [], "type": "array", "items": { "type": "string" } }, "bcc": { "example": [], "type": "array", "items": { "type": "string" } }, "subject": { "type": "string", "example": "Re: Pricing question" }, "snippet": { "type": "string", "nullable": true, "example": "Thanks for the details, this works for us.", "description": "Short preview of the message. Always present in list results." }, "isUnread": { "type": "boolean", "nullable": true, "example": true, "description": "Read state. `null` when the email is not part of a conversation and therefore has no read state, which is not the same as read." }, "type": { "type": "string", "enum": [ "sent", "received" ], "example": "received" }, "campaignId": { "type": "string", "nullable": true, "example": "c1f3b0a2-6d4e-4f8b-9a1c-2e5d7f0a3b6c" }, "leadId": { "type": "string", "nullable": true, "example": "9d4e2f10-5b6a-4c73-8e19-0f2a7c4d8b31" }, "hasAttachments": { "type": "boolean", "example": false }, "receivedAt": { "type": "string", "format": "date-time", "example": "2026-07-13T09:24:11.000Z" }, "sentAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-07-13T09:24:09.000Z" } }, "required": [ "id", "threadId", "messageId", "mailbox", "from", "to", "cc", "bcc", "subject", "snippet", "isUnread", "type", "campaignId", "leadId", "hasAttachments", "receivedAt", "sentAt" ] }, "EmailListMetaDto": { "type": "object", "properties": { "hasMore": { "type": "boolean", "example": true }, "nextCursor": { "type": "string", "nullable": true, "example": "eyJ0cyI6IjIwMjYtMDctMDJUMDA6MDA6MDAuMDAwWiIsImlkIjoiM2YxYzJiN2UtOWE0ZC00ZTE4LWIyYzEtNmQ4ZjVhMGU3YzkzIn0", "description": "Pass as `?cursor=` for the next page; `null` on the last page." } }, "required": [ "hasMore", "nextCursor" ] }, "EmailListApiResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailApiDto" } }, "meta": { "$ref": "#/components/schemas/EmailListMetaDto" } }, "required": [ "data", "meta" ] }, "UnreadCountApiResponseDto": { "type": "object", "properties": { "count": { "type": "number", "example": 12, "description": "Number of unread emails matching the filters." } }, "required": [ "count" ] }, "EmailBodyDto": { "type": "object", "properties": { "html": { "type": "string", "nullable": true, "example": "

Thanks for the details, this works for us.

", "description": "HTML body. `null` when the message has no HTML part." }, "text": { "type": "string", "nullable": true, "example": "Thanks for the details, this works for us.", "description": "Plain-text body. `null` when the message has no text part." } }, "required": [ "html", "text" ] }, "EmailDetailApiDto": { "type": "object", "properties": { "id": { "type": "string", "example": "8c5a1e07-2b93-4d6f-a0e8-7c4b9d1f2a36" }, "threadId": { "type": "string", "nullable": true, "example": "13a265fd-f0f2-b1d1-d6fc-154e483183e7", "description": "Conversation this email belongs to. `null` when the email is not part of a conversation. An opaque identifier: pass it back as-is, do not parse or construct it." }, "messageId": { "type": "string", "nullable": true, "example": "", "description": "RFC 5322 Message-ID as set by the sending server." }, "mailbox": { "nullable": true, "description": "The mailbox of yours that sent or received this email.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/EmailMailboxDto" } ] }, "from": { "$ref": "#/components/schemas/EmailParticipantDto" }, "to": { "example": [ "jane@acme.com" ], "type": "array", "items": { "type": "string" } }, "cc": { "example": [], "type": "array", "items": { "type": "string" } }, "bcc": { "example": [], "type": "array", "items": { "type": "string" } }, "subject": { "type": "string", "example": "Re: Pricing question" }, "snippet": { "type": "string", "nullable": true, "example": "Thanks for the details, this works for us.", "description": "Short preview of the message. Always present in list results." }, "isUnread": { "type": "boolean", "nullable": true, "example": true, "description": "Read state. `null` when the email is not part of a conversation and therefore has no read state, which is not the same as read." }, "type": { "type": "string", "enum": [ "sent", "received" ], "example": "received" }, "campaignId": { "type": "string", "nullable": true, "example": "c1f3b0a2-6d4e-4f8b-9a1c-2e5d7f0a3b6c" }, "leadId": { "type": "string", "nullable": true, "example": "9d4e2f10-5b6a-4c73-8e19-0f2a7c4d8b31" }, "hasAttachments": { "type": "boolean", "example": false }, "receivedAt": { "type": "string", "format": "date-time", "example": "2026-07-13T09:24:11.000Z" }, "sentAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-07-13T09:24:09.000Z" }, "body": { "description": "The message body. Returned only here, never in list results. A `null` field means that part was never stored for this message. It does NOT mean we failed to read it: if the stored body is unreadable right now, the call returns `503` instead, so a `200` always carries the real content.", "allOf": [ { "$ref": "#/components/schemas/EmailBodyDto" } ] } }, "required": [ "id", "threadId", "messageId", "mailbox", "from", "to", "cc", "bcc", "subject", "snippet", "isUnread", "type", "campaignId", "leadId", "hasAttachments", "receivedAt", "sentAt", "body" ] }, "EmailBodyInputApiDto": { "type": "object", "properties": { "html": { "type": "string", "example": "

Thanks, that works for me.

" }, "text": { "type": "string", "example": "Thanks, that works for me." } } }, "ReplyEmailApiDto": { "type": "object", "properties": { "body": { "$ref": "#/components/schemas/EmailBodyInputApiDto" }, "cc": { "example": [ "cto@acme.com" ], "description": "Additional recipients in copy.", "type": "array", "items": { "type": "string" } }, "bcc": { "example": [ "crm@acme.com" ], "type": "array", "items": { "type": "string" } } }, "required": [ "body" ] }, "SendEmailApiResponseDto": { "type": "object", "properties": { "id": { "type": "string", "example": "5e9a3c81-7d24-4b60-9f13-8a6c2e0d4b57", "description": "The email that was queued for sending." }, "threadId": { "type": "string", "nullable": true, "example": "13a265fd-f0f2-b1d1-d6fc-154e483183e7" }, "status": { "type": "string", "example": "queued", "description": "The email is queued for delivery. Poll the email to see it sent." } }, "required": [ "id", "threadId", "status" ] }, "ForwardEmailApiDto": { "type": "object", "properties": { "to": { "example": [ "colleague@acme.com" ], "type": "array", "items": { "type": "string" } }, "body": { "description": "Your note above the forwarded message. The original message is quoted for you.", "allOf": [ { "$ref": "#/components/schemas/EmailBodyInputApiDto" } ] }, "cc": { "example": [ "cto@acme.com" ], "type": "array", "items": { "type": "string" } }, "bcc": { "example": [ "crm@acme.com" ], "type": "array", "items": { "type": "string" } }, "subject": { "type": "string", "example": "Fwd: Pricing question", "description": "Overrides the default `Fwd:` subject." } }, "required": [ "to" ] }, "MarkThreadReadApiResponseDto": { "type": "object", "properties": { "threadId": { "type": "string", "example": "13a265fd-f0f2-b1d1-d6fc-154e483183e7" }, "unreadCount": { "type": "number", "example": 0, "description": "Emails left unread in the conversation." } }, "required": [ "threadId", "unreadCount" ] }, "AnalyticsPeriodView": { "type": "object", "properties": { "start": { "type": "string", "example": "2026-06-01T00:00:00.000Z" }, "end": { "type": "string", "example": "2026-06-30T23:59:59.000Z" }, "clamped": { "type": "boolean", "example": false, "description": "true = your requested start was older than the plan retention window and was moved forward. The data you got is real but shorter than you asked for." }, "retentionDays": { "type": "number", "example": 90, "description": "Days of history your plan retains." } }, "required": [ "start", "end", "clamped", "retentionDays" ] }, "EngagementCountView": { "type": "object", "properties": { "total": { "type": "number", "example": 240, "description": "Opens/clicks counted per email (bots excluded): the same email opened twice counts once, two different steps count twice." }, "uniqueLeads": { "type": "number", "example": 180, "description": "Distinct leads who did this at least once." } }, "required": [ "total", "uniqueLeads" ] }, "AnalyticsRatesView": { "type": "object", "properties": { "open": { "type": "number", "example": 42.5, "nullable": true, "description": "uniqueLeads opened / leads contacted." }, "click": { "type": "number", "example": 8.1, "nullable": true, "description": "uniqueLeads clicked / leads contacted." }, "reply": { "type": "number", "example": 4.2, "nullable": true, "description": "uniqueLeads replied / leads contacted." }, "bounce": { "type": "number", "example": 1.9, "nullable": true, "description": "bounces / sent." }, "delivery": { "type": "number", "example": 98.1, "nullable": true, "description": "delivered / sent." }, "unsubscribe": { "type": "number", "example": 0.4, "nullable": true, "description": "unsubscribes / sent." }, "conversion": { "type": "number", "example": 2, "nullable": true, "description": "conversions / leads contacted." } }, "required": [ "open", "click", "reply", "bounce", "delivery", "unsubscribe", "conversion" ] }, "AnalyticsTotalsView": { "type": "object", "properties": { "sent": { "type": "number", "example": 1200, "description": "Emails handed to the provider." }, "failed": { "type": "number", "example": 8, "description": "Sends that permanently failed before delivery." }, "delivered": { "type": "number", "example": 1186, "description": "Sent minus bounced." }, "leadsContacted": { "type": "number", "example": 640, "description": "Distinct leads that received at least one email." }, "opens": { "$ref": "#/components/schemas/EngagementCountView" }, "clicks": { "$ref": "#/components/schemas/EngagementCountView" }, "replies": { "type": "number", "example": 26, "description": "Distinct leads who replied." }, "bounces": { "type": "number", "example": 14, "description": "All bounces. Ask for `breakdown=bounce` to split hard/soft and by reason." }, "unsubscribed": { "type": "number", "example": 5, "description": "Unsubscribes in the window." }, "positiveLeads": { "type": "number", "example": 21, "description": "Leads currently in a positive state (interested / meeting / converted)." }, "conversions": { "type": "number", "example": 6, "description": "Conversions attributed in the window." }, "conversionValue": { "type": "number", "example": 18000, "nullable": true, "description": "Total value of those conversions, in your workspace currency." }, "rates": { "$ref": "#/components/schemas/AnalyticsRatesView" } }, "required": [ "sent", "failed", "delivered", "leadsContacted", "opens", "clicks", "replies", "bounces", "unsubscribed", "positiveLeads", "conversions", "rates" ] }, "WorkspaceCampaignRollupView": { "type": "object", "properties": { "campaignId": { "type": "string", "example": "c1a2b3d4-..." }, "name": { "type": "string", "example": "Q3 outbound – DACH" }, "sent": { "type": "number", "example": 1200 }, "openRate": { "type": "number", "example": 42.5, "nullable": true } }, "required": [ "campaignId", "name", "sent", "openRate" ] }, "WorkspaceAnalyticsApiResponseDto": { "type": "object", "properties": { "period": { "$ref": "#/components/schemas/AnalyticsPeriodView" }, "totals": { "description": "Rolled up across every campaign in the workspace.", "allOf": [ { "$ref": "#/components/schemas/AnalyticsTotalsView" } ] }, "activeCampaigns": { "type": "number", "example": 7, "description": "Campaigns currently sending." }, "sendingAccounts": { "type": "number", "example": 12, "description": "Connected sending accounts." }, "topCampaigns": { "description": "Highest-volume campaigns in the window.", "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceCampaignRollupView" } } }, "required": [ "period", "totals", "activeCampaigns", "sendingAccounts", "topCampaigns" ] }, "AnalyticsTimeseriesPointView": { "type": "object", "properties": { "timestamp": { "type": "string", "example": "2026-06-14T00:00:00.000Z", "description": "Start of the bucket." }, "sent": { "type": "number", "example": 120 }, "delivered": { "type": "number", "example": 118 }, "opens": { "$ref": "#/components/schemas/EngagementCountView" }, "clicks": { "$ref": "#/components/schemas/EngagementCountView" }, "replies": { "type": "number", "example": 4 }, "bounces": { "type": "number", "example": 2 }, "unsubscribed": { "type": "number", "example": 1, "description": "Unsubscribes in this bucket." } }, "required": [ "timestamp", "sent", "delivered", "opens", "clicks", "replies", "bounces", "unsubscribed" ] }, "AnalyticsTimeseriesApiResponseDto": { "type": "object", "properties": { "campaignId": { "type": "string", "example": "c1a2b3d4-..." }, "period": { "$ref": "#/components/schemas/AnalyticsPeriodView" }, "interval": { "type": "string", "example": "day", "enum": [ "day", "week", "month" ], "description": "Bucket size actually used – may be coarser than requested for long windows." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsTimeseriesPointView" } } }, "required": [ "campaignId", "period", "interval", "data" ] }, "BreakdownRatesView": { "type": "object", "properties": { "open": { "type": "number", "example": 42.5, "nullable": true }, "click": { "type": "number", "example": 8.1, "nullable": true }, "reply": { "type": "number", "example": 4.2, "nullable": true }, "bounce": { "type": "number", "example": 1.9, "nullable": true }, "delivery": { "type": "number", "example": 98.1, "nullable": true }, "positive": { "type": "number", "example": 41.7, "nullable": true, "description": "Share of replied leads whose status is positive now (interested / meeting / converted), %. null when nobody replied." }, "conversion": { "type": "number", "example": 1.5, "nullable": true, "description": "conversions / leads contacted." } }, "required": [ "open", "click", "reply", "bounce", "delivery", "positive", "conversion" ] }, "BreakdownTotalsView": { "type": "object", "properties": { "sent": { "type": "number", "example": 400 }, "delivered": { "type": "number", "example": 396 }, "opens": { "$ref": "#/components/schemas/EngagementCountView" }, "clicks": { "$ref": "#/components/schemas/EngagementCountView" }, "replies": { "type": "number", "example": 12, "description": "Distinct leads who replied." }, "bounces": { "type": "number", "example": 4 }, "positiveLeads": { "type": "number", "example": 3, "description": "Leads currently in a positive state (interested / meeting / converted)." }, "conversions": { "type": "number", "example": 2, "description": "Conversions attributed to this row." }, "conversionValue": { "type": "number", "example": 6000, "nullable": true, "description": "Total value of those conversions, in your workspace currency." }, "rates": { "$ref": "#/components/schemas/BreakdownRatesView" } }, "required": [ "sent", "delivered", "opens", "clicks", "replies", "bounces", "positiveLeads", "conversions", "rates" ] }, "SmtpBreakdownView": { "type": "object", "properties": { "accountId": { "type": "string", "example": "a7f1c2d4-..." }, "email": { "type": "string", "example": "outreach@acme.com", "nullable": true, "description": "Sending account address. null when the account name is unavailable." }, "totals": { "$ref": "#/components/schemas/BreakdownTotalsView" } }, "required": [ "accountId", "email", "totals" ] }, "SequenceBreakdownView": { "type": "object", "properties": { "step": { "type": "number", "example": 1, "description": "Sequence step number." }, "variant": { "type": "string", "example": "A", "description": "A/B variant letter." }, "totals": { "$ref": "#/components/schemas/BreakdownTotalsView" } }, "required": [ "step", "variant", "totals" ] }, "BounceCategoryView": { "type": "object", "properties": { "category": { "type": "string", "example": "invalid-mailbox", "description": "Machine-readable category." }, "label": { "type": "string", "example": "Invalid mailbox", "description": "Human-readable label." }, "type": { "type": "string", "example": "recipient", "enum": [ "sender", "recipient", "unknown" ], "description": "Who is responsible: sender (reputation/auth/content – fix your sending), recipient (bad address – clean your list), or unknown." }, "count": { "type": "number", "example": 9, "description": "Unique messages that ended in this category." }, "percentage": { "type": "number", "example": 64.3, "description": "Share of all bounces, percent. Category counts sum to `total`." } }, "required": [ "category", "label", "type", "count", "percentage" ] }, "BounceBreakdownView": { "type": "object", "properties": { "total": { "type": "number", "example": 14 }, "hard": { "type": "number", "example": 9, "description": "Permanent failures (5xx) – the address is bad; drop it from the list." }, "soft": { "type": "number", "example": 5, "description": "Temporary failures (4xx) – mailbox full, greylisting, throttling." }, "senderBounces": { "type": "number", "example": 3, "description": "Bounces caused by the sender side (reputation, auth, content)." }, "recipientBounces": { "type": "number", "example": 11, "description": "Bounces caused by the recipient side (bad address, disabled mailbox)." }, "unknownBounces": { "type": "number", "example": 0, "description": "Bounces we could not attribute to either side." }, "byCategory": { "type": "array", "items": { "$ref": "#/components/schemas/BounceCategoryView" } } }, "required": [ "total", "hard", "soft", "senderBounces", "recipientBounces", "unknownBounces", "byCategory" ] }, "CampaignAnalyticsApiResponseDto": { "type": "object", "properties": { "campaignId": { "type": "string", "example": "c1a2b3d4-..." }, "period": { "$ref": "#/components/schemas/AnalyticsPeriodView" }, "totals": { "$ref": "#/components/schemas/AnalyticsTotalsView" }, "bySmtp": { "description": "Present only when requested via `breakdown=smtp`.", "type": "array", "items": { "$ref": "#/components/schemas/SmtpBreakdownView" } }, "bySequence": { "description": "Present only when requested via `breakdown=sequence`.", "type": "array", "items": { "$ref": "#/components/schemas/SequenceBreakdownView" } }, "bounceBreakdown": { "description": "Present only when requested via `breakdown=bounce`.", "allOf": [ { "$ref": "#/components/schemas/BounceBreakdownView" } ] } }, "required": [ "campaignId", "period", "totals" ] }, "LeadSearchListItemApiDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60" }, "query": { "type": "string", "example": "dental clinics in Berlin", "description": "The natural-language query this search was started from." }, "status": { "type": "string", "enum": [ "draft", "queued", "discovering", "processing", "crawling", "enriching", "verifying", "completed", "stopped", "failed" ], "example": "completed", "description": "Lifecycle status. Terminal states are `completed`, `stopped`, `failed`; everything else is still running." }, "searchMode": { "type": "string", "enum": [ "companies", "people" ], "example": "companies", "description": "Whether the search discovers companies or people." }, "maxResults": { "type": "number", "example": 500, "description": "The requested discovery cap for this search." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the search was created." }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the search reached a terminal state; null while still running." } }, "required": [ "id", "query", "status", "searchMode", "maxResults", "createdAt" ] }, "LeadSearchListMetaApiDto": { "type": "object", "properties": { "hasMore": { "type": "boolean", "example": true, "description": "Whether more searches are available after this page." }, "nextCursor": { "type": "string", "nullable": true, "description": "Pass as `?cursor=` to fetch the next page; null when `hasMore` is false.", "example": "eyJ0cyI6IjIwMjYtMDctMDJUMDA6MDA6MDAuMDAwWiIsImlkIjoiM2YxYzJiN2UtOWE0ZC00ZTE4LWIyYzEtNmQ4ZjVhMGU3YzkzIn0" } }, "required": [ "hasMore" ] }, "LeadSearchListApiResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeadSearchListItemApiDto" } }, "meta": { "$ref": "#/components/schemas/LeadSearchListMetaApiDto" } }, "required": [ "data", "meta" ] }, "LeadSearchProgressApiDto": { "type": "object", "properties": { "companiesFound": { "type": "number", "example": 183, "description": "Companies discovered so far." }, "companiesProcessed": { "type": "number", "example": 60, "description": "Of the discovered companies, how many have finished contact processing (crawled for emails/phones – including those with nothing found). Grows toward `companiesFound` as the run progresses." }, "emailsFound": { "type": "number", "example": 137, "description": "Email addresses discovered so far." } }, "required": [ "companiesFound", "companiesProcessed", "emailsFound" ] }, "LeadSearchApiDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "a7d4e2f1-08b3-4c65-9e7a-1b2c3d4e5f60" }, "query": { "type": "string", "example": "dental clinics in Berlin" }, "status": { "type": "string", "enum": [ "draft", "queued", "discovering", "processing", "crawling", "enriching", "verifying", "completed", "stopped", "failed" ], "example": "processing" }, "searchMode": { "type": "string", "enum": [ "companies", "people" ], "example": "companies" }, "maxResults": { "type": "number", "example": 500 }, "discoveryFinished": { "type": "boolean", "example": true, "description": "Whether the discovery phase has finished (crawl/enrich may still run)." }, "progress": { "$ref": "#/components/schemas/LeadSearchProgressApiDto" }, "errorMessage": { "type": "string", "nullable": true, "description": "Failure reason when `status` is `failed`; otherwise null." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the search row was last updated." }, "completedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the search reached a terminal state; null while still running." } }, "required": [ "id", "query", "status", "searchMode", "maxResults", "discoveryFinished", "progress", "createdAt", "updatedAt" ] } } } }