{ "openapi": "3.1.0", "info": { "title": "GhostParse API", "version": "1.2.0", "summary": "Free inbound email API: receive email as signed JSON webhooks, with extraction, an instant address and a CLI.", "description": "Inbound email parsing. Full guide: https://ghostparse.com/docs. Operated by WILDYE LIMITED.", "termsOfService": "https://ghostparse.com/terms", "contact": { "email": "hello@wildye.com" } }, "servers": [ { "url": "https://ghostparse.com" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Webhooks", "description": "Inbound email delivery to your endpoint" }, { "name": "Domains", "description": "Provision domains and email addresses (API keys with the domains scope)" }, { "name": "Inbound", "description": "Delivery log and signed reply addresses" }, { "name": "Resellers", "description": "Sub-accounts for your own customers (reseller accounts; keys with the accounts scope)" }, { "name": "Integrations", "description": "Zapier, Make and n8n (REST hooks), Slack, Teams and Google Sheets destinations, routing rules (keys with the integrations scope)" }, { "name": "Platform", "description": "Public facts about this platform" } ], "paths": { "/v1/webhooks/test": { "post": { "tags": [ "Webhooks" ], "operationId": "sendTestWebhook", "summary": "Send a test event to your webhook URL", "responses": { "200": { "description": "Delivered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestResult" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Your endpoint didn't accept it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestResult" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "main", "backup" ], "default": "main" } } } } } } }, "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ] }, "/v1/webhook": { "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ], "get": { "tags": [ "Webhooks" ], "operationId": "getWebhookSettings", "summary": "Webhook settings", "description": "Needs the domains scope.", "responses": { "200": { "description": "Settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSettings" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Webhooks" ], "operationId": "updateWebhookSettings", "summary": "Change webhook settings", "description": "Needs the domains scope.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSettingsUpdate" }, "example": { "webhook_url": "https://yourapp.com/webhooks/email", "backup_webhook_url": "https://backup.yourapp.com/webhooks/email" } } } }, "responses": { "200": { "description": "Settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSettings" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "secret_incompatible: rotate the secret before switching to standard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid URL or setting", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook/secret/rotate": { "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ], "post": { "tags": [ "Webhooks" ], "operationId": "rotateWebhookSecret", "summary": "New signing secret", "description": "The old secret keeps working for 24 hours (webhooks carry both signatures) unless immediate is true.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "immediate": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "The new secret (shown once)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretRotation" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/inbox": { "get": { "tags": [ "Inbound" ], "operationId": "getInbox", "summary": "Your instant inbox address", "description": "Every account gets an address on the platform's own domain that receives mail before any DNS setup. Any API key may call this.", "responses": { "200": { "description": "The address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inbox" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ] }, "/v1/samples": { "post": { "tags": [ "Inbound" ], "operationId": "sendSample", "summary": "Send a sample email through the real pipeline", "description": "A realistic customer reply (quoted history, an attachment, header X-Email-Parser-Sample: true) is parsed, checked, run through the address's parser and delivered to your webhook or CLI listener, and logged. 10 per minute. Any API key may call this.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "description": "One of your receiving addresses (default: your instant inbox address)" } } }, "example": {} } } }, "responses": { "200": { "description": "What happened", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SampleResult" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "no_receiving_address or not_receiving", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ] }, "/v1/listen": { "get": { "tags": [ "Inbound" ], "operationId": "listen", "summary": "Stream deliveries to the CLI (Server-Sent Events)", "description": "Used by `email-parser listen`. Events: `ready`, then `delivery` with `{delivery_id, mirror, headers, body}` (body base64): replay it as a POST to your local endpoint, then report the status to /v1/listen/ack unless `mirror` is true. Without a webhook URL on the account, the listener is where mail goes; with one, it gets copies.", "responses": { "200": { "description": "An open event stream", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ] }, "/v1/listen/ack": { "post": { "tags": [ "Inbound" ], "operationId": "listenAck", "summary": "Report a local endpoint's response for a streamed delivery", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "delivery_id", "status" ], "properties": { "delivery_id": { "type": "string" }, "status": { "type": "integer", "description": "The local endpoint's HTTP status; 0 if it couldn't be reached" }, "error": { "type": "string" } } }, "example": { "delivery_id": "6f1c…", "status": 200 } } } }, "responses": { "200": { "description": "acknowledged is false for unknown or already-timed-out deliveries", "content": { "application/json": { "schema": { "type": "object", "properties": { "acknowledged": { "type": "boolean" } } } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ] }, "/v1/deliveries": { "get": { "tags": [ "Inbound" ], "operationId": "listDeliveries", "summary": "Recent inbound deliveries (newest first)", "description": "Kept for 90 days. Any API key may call this.", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "delivered", "deferred", "failed", "rejected", "dropped" ] } }, { "name": "domain_id", "in": "query", "schema": { "type": "string" } }, { "name": "message_id", "in": "query", "schema": { "type": "string" }, "description": "Exact Message-ID, with the angle brackets" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "before", "in": "query", "schema": { "type": "integer" }, "description": "next_before from the previous page" } ], "responses": { "200": { "description": "A page of deliveries", "content": { "application/json": { "schema": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } }, "next_before": { "type": [ "integer", "null" ] } } } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ] }, "/v1/usage": { "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ], "get": { "tags": [ "Inbound" ], "operationId": "getUsage", "summary": "This billing period's usage and plan", "description": "Any API key may call this. Inbound emails over a Free plan's allowance (plus 10%) are deferred; paid plans bill them.", "responses": { "200": { "description": "Usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reply-addresses": { "post": { "tags": [ "Inbound" ], "operationId": "createReplyAddress", "summary": "Make a signed reply address", "description": "Use it as the Reply-To of a notification. Replies arrive with recipients[].tag set and tag_verified true; nobody else can make valid ones. Any API key may call this.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyAddressRequest" }, "example": { "address": "support@acme.com", "tag": "t42" } } } }, "responses": { "200": { "description": "The address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyAddress" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: the domain isn't on your account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_address, invalid_tag, address_not_receiving or validation_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ] }, "/v1/domains": { "get": { "tags": [ "Domains" ], "operationId": "listDomains", "summary": "List domains", "parameters": [ { "name": "reference", "in": "query", "schema": { "type": "string" } }, { "name": "name", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Domains", "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } } } } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the domains scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Domains" ], "operationId": "createDomain", "summary": "Add a domain (optionally with addresses and settings)", "description": "Created atomically: if any part is invalid, nothing is created. Returns the DNS records to publish.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainCreate" }, "example": { "name": "customer-shop.com", "reference": "hosting-customer-1001", "inbound_enabled": true, "webhook_url": "https://customer-shop.com/webhooks/email", "addresses": [ { "local_part": "info", "can_send": true, "can_receive": true }, { "local_part": "noreply", "can_send": true, "can_receive": false } ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the domains scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "domain_exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "validation_error, invalid_domain, invalid_address, wrong_domain, duplicate_address, no_permissions, invalid_reference, invalid_webhook_url, too_many_domains, too_many_addresses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ] }, "/v1/domains/{id}": { "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ], "get": { "tags": [ "Domains" ], "operationId": "getDomain", "summary": "Get a domain", "responses": { "200": { "description": "Domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the domains scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Domains" ], "operationId": "updateDomain", "summary": "Update inbound, webhook URL or reference", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainUpdate" }, "example": { "inbound_enabled": false } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the domains scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "validation_error, invalid_reference, invalid_webhook_url", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Domains" ], "operationId": "deleteDomain", "summary": "Remove a domain and its addresses", "responses": { "204": { "description": "Deleted" }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the domains scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/domains/{id}/verify": { "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ], "post": { "tags": [ "Domains" ], "operationId": "verifyDomain", "summary": "Check the domain's DNS records now", "description": "Limited to 30 requests per minute per key. DNS can take minutes to propagate: retry with backoff.", "responses": { "200": { "description": "Check results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResult" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the domains scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/domains/{id}/addresses": { "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ], "post": { "tags": [ "Domains" ], "operationId": "addAddress", "summary": "Add an email address", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressCreate" }, "example": { "local_part": "billing", "can_send": true, "can_receive": false } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainAddress" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the domains scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "address_exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "validation_error, invalid_address, wrong_domain, no_permissions, too_many_addresses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/domains/{id}/addresses/{addressId}": { "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ], "patch": { "tags": [ "Domains" ], "operationId": "updateAddress", "summary": "Change an address's permissions, webhook or signed-tag requirement", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressUpdate" }, "example": { "can_receive": true } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainAddress" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the domains scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "no_permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Domains" ], "operationId": "removeAddress", "summary": "Remove an email address", "responses": { "204": { "description": "Removed" }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the domains scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/domains/{id}/sender-rules": { "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ], "get": { "tags": [ "Domains" ], "operationId": "listSenderRules", "summary": "List a domain's sender rules", "responses": { "200": { "description": "Rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "sender_rules": { "type": "array", "items": { "$ref": "#/components/schemas/SenderRule" } } } } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the domains scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Domains" ], "operationId": "addSenderRule", "summary": "Block a sender, or allow only listed senders", "description": "Allow-listed senders must pass authentication (DMARC, or DKIM/SPF for their domain when it has no DMARC record).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderRuleCreate" }, "example": { "action": "block", "pattern": "spammer.example" } } } }, "responses": { "201": { "description": "Added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SenderRule" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the domains scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "rule_exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_pattern, too_many_rules or validation_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/domains/{id}/sender-rules/{ruleId}": { "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ], "delete": { "tags": [ "Domains" ], "operationId": "removeSenderRule", "summary": "Remove a sender rule", "responses": { "204": { "description": "Removed" }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the domains scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/accounts": { "get": { "tags": [ "Resellers" ], "operationId": "listSubaccounts", "summary": "List your sub-accounts", "parameters": [ { "name": "reference", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sub-accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/Subaccount" } } } } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "not_reseller or insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Resellers" ], "operationId": "createSubaccount", "summary": "Create a sub-account", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubaccountCreate" }, "example": { "name": "Bob's Bakery", "reference": "cust-77", "webhook_url": "https://bobsbakery.example/webhooks/email" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubaccountCreated" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "not_reseller or insufficient_scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input, or too_many_accounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/accounts/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Resellers" ], "operationId": "getSubaccount", "summary": "A sub-account", "responses": { "200": { "description": "The sub-account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subaccount" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "account_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Resellers" ], "operationId": "updateSubaccount", "summary": "Rename, re-reference or suspend", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubaccountUpdate" }, "example": { "suspended": true } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subaccount" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "account_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Resellers" ], "operationId": "deleteSubaccount", "summary": "Delete a sub-account and everything in it", "responses": { "204": { "description": "Deleted" }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "account_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/accounts/{id}/invitations": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Resellers" ], "operationId": "inviteToSubaccount", "summary": "Invite someone to a sub-account's dashboard", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationCreate" }, "example": { "email": "owner@bobsbakery.example", "role": "owner" } } } }, "responses": { "201": { "description": "Invitation sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invitation" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "account_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "email_taken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/me": { "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ], "get": { "tags": [ "Integrations" ], "operationId": "getMe", "summary": "The account and API key making the request", "description": "Any API key may call this. Automation platforms use it to test a connection.", "responses": { "200": { "description": "Account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/hooks": { "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ], "get": { "tags": [ "Integrations" ], "operationId": "listHooks", "summary": "List REST hook subscriptions", "responses": { "200": { "description": "Hooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "hooks": { "type": "array", "items": { "$ref": "#/components/schemas/Hook" } } } } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the integrations permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Integrations" ], "operationId": "subscribeHook", "summary": "Subscribe a URL to email.received", "description": "Each email is POSTed to target_url as a signed JSON event. Answer 410 to unsubscribe.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HookCreate" }, "example": { "target_url": "https://hooks.zapier.com/hooks/standard/123/abc/", "source": "zapier", "filter": { "address": "invoices@*" } } } } }, "responses": { "201": { "description": "Subscribed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HookCreated" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the integrations permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_destination or validation_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/hooks/sample": { "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ], "get": { "tags": [ "Integrations" ], "operationId": "sampleHookEvent", "summary": "A sample email.received event, in an array", "responses": { "200": { "description": "Sample events", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the integrations permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/hooks/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/AccountHeader" } ], "delete": { "tags": [ "Integrations" ], "operationId": "unsubscribeHook", "summary": "Unsubscribe", "responses": { "204": { "description": "Unsubscribed" }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the integrations permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "hook_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/destinations": { "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ], "get": { "tags": [ "Integrations" ], "operationId": "listDestinations", "summary": "List destinations", "responses": { "200": { "description": "Destinations", "content": { "application/json": { "schema": { "type": "object", "properties": { "destinations": { "type": "array", "items": { "$ref": "#/components/schemas/Destination" } } } } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the integrations permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Integrations" ], "operationId": "createDestination", "summary": "Add a destination (Slack, Teams, Google Sheets or a webhook)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationCreate" }, "example": { "type": "slack", "name": "#support", "url": "https://hooks.slack.com/services/T000/B000/XXXX", "all_mail": true, "filter": { "address": "support@*" } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Destination" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the integrations permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_destination, too_many_destinations or validation_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/destinations/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/AccountHeader" } ], "get": { "tags": [ "Integrations" ], "operationId": "getDestination", "summary": "A destination", "responses": { "200": { "description": "Destination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Destination" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the integrations permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "destination_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Integrations" ], "operationId": "updateDestination", "summary": "Change a destination", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationUpdate" }, "example": { "enabled": false } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Destination" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the integrations permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "destination_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_destination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Integrations" ], "operationId": "deleteDestination", "summary": "Delete a destination (routing rules stop sending to it)", "responses": { "204": { "description": "Deleted" }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the integrations permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "destination_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/destinations/{id}/test": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/AccountHeader" } ], "post": { "tags": [ "Integrations" ], "operationId": "testDestination", "summary": "Send the sample email to a destination", "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivered": { "type": "boolean" }, "status": { "type": "integer" }, "error": { "type": "string" } }, "required": [ "delivered" ] } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the integrations permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "destination_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/rules": { "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ], "get": { "tags": [ "Integrations" ], "operationId": "listRules", "summary": "List routing rules, in order", "responses": { "200": { "description": "Rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingRule" } } } } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the integrations permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Integrations" ], "operationId": "createRule", "summary": "Add a routing rule", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingRuleCreate" }, "example": { "name": "Invoices to the finance sheet", "conditions": [ { "field": "from_domain", "op": "ends_with", "value": "stripe.com" }, { "field": "subject", "op": "contains", "value": "invoice" } ], "action": "route", "targets": [ "webhook" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingRule" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the integrations permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_rule, too_many_routing_rules or validation_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/rules/test": { "parameters": [ { "$ref": "#/components/parameters/AccountHeader" } ], "post": { "tags": [ "Integrations" ], "operationId": "testRules", "summary": "Where would this email go? Nothing is sent.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleTest" }, "example": { "subject": "Your invoice", "from": "billing@stripe.com", "to": "accounts@yourapp.com" } } } }, "responses": { "200": { "description": "Decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingDecision" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the integrations permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/rules/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/AccountHeader" } ], "get": { "tags": [ "Integrations" ], "operationId": "getRule", "summary": "A routing rule", "responses": { "200": { "description": "Rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingRule" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the integrations permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "rule_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Integrations" ], "operationId": "updateRule", "summary": "Change a rule, or move it (position)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingRuleUpdate" }, "example": { "position": 1 } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingRule" } } } }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the integrations permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "rule_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_rule", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Integrations" ], "operationId": "deleteRule", "summary": "Delete a rule", "responses": { "204": { "description": "Deleted" }, "401": { "description": "Missing, wrong or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope: the key needs the integrations permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "rule_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/meta": { "get": { "tags": [ "Platform" ], "operationId": "getMeta", "summary": "Webhook source IPs and data region", "description": "Public: no API key needed.", "security": [], "responses": { "200": { "description": "Platform facts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Meta" } } } } } } } }, "webhooks": { "emailReceived": { "post": { "summary": "An inbound email was received (sent to your webhook URL)", "description": "Verify the signature before trusting the body (our SDKs, or any Standard Webhooks library, do this). Standard Webhooks (the default): HMAC-SHA256 over \"..\" keyed with the base64-decoded part of your whsec_ secret, sent as `webhook-signature: v1,` (space-separated when two secrets are valid during a rotation). Accounts on the original format get `webhook-signature: t=,v1=.\" keyed with the whole secret>`. Respond 2xx within 10 s. De-duplicate on data.message_id. If you set a backup webhook URL, it receives the same signed request when this endpoint is unreachable or returns 5xx.", "security": [], "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Equals the event id; the same on every retry." }, { "name": "webhook-timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "example": "1790932497", "description": "Unix seconds when this attempt was signed" }, { "name": "webhook-signature", "in": "header", "required": true, "schema": { "type": "string" }, "example": "v1,unqzZ64edPDGcZVcnf3zGnmbc6EQ6DznDhh3jhZXPIE=" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "200": { "description": "Any 2xx acknowledges the event" }, "400": { "description": "Signature verification failed. Other 4xx (except 408/429) bounce the email; 5xx/timeouts are retried." } }, "operationId": "emailReceived" } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "API key from the dashboard (ek_live_…). /v1/domains needs the domains scope." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Machine-readable code, e.g. sender_not_allowed" }, "message": { "type": "string" }, "statusCode": { "type": "integer" } } }, "WebhookTestResult": { "type": "object", "required": [ "delivered" ], "properties": { "delivered": { "type": "boolean" }, "event_id": { "type": "string" }, "error": { "type": "string" } } }, "WebhookEvent": { "type": "object", "required": [ "id", "type", "timestamp", "created_at", "tenant_id", "data" ], "properties": { "id": { "type": "string", "example": "evt_6c1d…" }, "type": { "type": "string", "enum": [ "email.received", "webhook.test" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "Standard Webhooks payload field (same as created_at)" }, "created_at": { "type": "string", "format": "date-time" }, "tenant_id": { "type": "string", "description": "Your account ID" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/InboundEmail" }, { "type": "object", "properties": { "message": { "type": "string" } }, "description": "webhook.test" } ] } } }, "ParsedAddress": { "type": "object", "properties": { "address": { "type": "string" }, "name": { "type": "string" } } }, "InboundAttachment": { "type": "object", "properties": { "filename": { "type": [ "string", "null" ], "description": "From the sender: sanitise before saving" }, "content_type": { "type": "string" }, "size": { "type": "integer" }, "content_id": { "type": [ "string", "null" ] }, "disposition": { "type": [ "string", "null" ] }, "content": { "type": [ "string", "null" ], "contentEncoding": "base64", "description": "null when attachments are delivered as separate parts (multipart) or left out" }, "sha256": { "type": "string", "description": "Hex SHA-256 of the file. In multipart deliveries, check the file part against this: the event JSON is what's signed." }, "part": { "type": "string", "example": "attachment_0", "description": "Multipart deliveries only: the form part holding this file" } } }, "Authentication": { "type": "object", "properties": { "verdict": { "type": "string", "enum": [ "pass", "fail", "none", "temperror", "permerror" ], "description": "DMARC result for the From domain" }, "spf": { "type": [ "object", "null" ], "properties": { "result": { "type": "string" }, "domain": { "type": [ "string", "null" ] }, "client_ip": { "type": [ "string", "null" ] } } }, "dkim": { "type": "array", "items": { "type": "object", "properties": { "result": { "type": "string" }, "domain": { "type": [ "string", "null" ] }, "selector": { "type": [ "string", "null" ] }, "aligned": { "type": "boolean" } } } }, "dmarc": { "type": [ "object", "null" ], "properties": { "result": { "type": "string" }, "policy": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] } } }, "arc": { "type": [ "object", "null" ], "properties": { "result": { "type": "string" } } }, "header": { "type": "string" } } }, "InboundEmail": { "type": "object", "properties": { "id": { "type": "string", "example": "inb_…" }, "message_id": { "type": [ "string", "null" ], "description": "De-duplicate on this" }, "envelope": { "type": "object", "properties": { "mail_from": { "type": [ "string", "null" ] }, "rcpt_to": { "type": "array", "items": { "type": "string" } }, "client_ip": { "type": [ "string", "null" ] }, "helo": { "type": [ "string", "null" ] } } }, "from": { "oneOf": [ { "$ref": "#/components/schemas/ParsedAddress" }, { "type": "null" } ] }, "to": { "type": "array", "items": { "$ref": "#/components/schemas/ParsedAddress" } }, "cc": { "type": "array", "items": { "$ref": "#/components/schemas/ParsedAddress" } }, "reply_to": { "type": "array", "items": { "$ref": "#/components/schemas/ParsedAddress" } }, "subject": { "type": [ "string", "null" ] }, "date": { "type": [ "string", "null" ], "format": "date-time" }, "in_reply_to": { "type": [ "string", "null" ] }, "references": { "type": "array", "items": { "type": "string" } }, "thread_id": { "type": "string", "example": "thr_836de45f552c568b8e3b9810", "description": "Same for every message in a conversation: see thread" }, "thread": { "$ref": "#/components/schemas/Thread" }, "text": { "type": [ "string", "null" ] }, "reply_text": { "type": [ "string", "null" ], "description": "Just the new part of a reply: quoted history (\"On … wrote:\", \"> \" lines, Outlook header blocks) and signature removed. Best effort: text has everything." }, "html": { "type": [ "string", "null" ] }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Lower-cased names" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/InboundAttachment" } }, "authentication": { "oneOf": [ { "$ref": "#/components/schemas/Authentication" }, { "type": "null" } ] }, "auto_submitted": { "type": [ "string", "null" ], "enum": [ "auto_reply", "bounce", "auto_generated", null ], "description": "Set for out-of-office replies, bounces and other machine-generated mail. Never auto-reply to these." }, "bounce": { "oneOf": [ { "$ref": "#/components/schemas/Bounce" }, { "type": "null" } ] }, "calendar": { "type": "array", "items": { "$ref": "#/components/schemas/CalendarEvent" }, "description": "Events from attached iCalendar invites (.ics)" }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/InboundRecipient" }, "description": "Your envelope recipients, split into base address and tag" }, "spam": { "oneOf": [ { "$ref": "#/components/schemas/SpamResult" }, { "type": "null" } ] }, "virus": { "oneOf": [ { "$ref": "#/components/schemas/VirusResult" }, { "type": "null" } ] }, "extracted": { "oneOf": [ { "$ref": "#/components/schemas/Extracted" }, { "type": "null" } ], "description": "Fields pulled out by the address's parser (rules or AI); null when the address has no parser." }, "size": { "type": "integer", "description": "Size of the original message in bytes" }, "raw": { "type": "string", "contentEncoding": "base64", "description": "The original message (.eml). Only when \"Include the original message\" is on and attachments are inline or omitted." }, "raw_part": { "type": "string", "const": "raw", "description": "Multipart deliveries with \"Include the original message\" on: the form part holding the .eml." }, "received_at": { "type": "string", "format": "date-time" } }, "description": "data of an email.received event. raw and raw_part only appear when the account asks for the original message." }, "AddressCreate": { "type": "object", "required": [ "local_part" ], "additionalProperties": false, "properties": { "local_part": { "type": "string", "description": "The part before the @ (no +). \"name@domain\" is accepted if the domain matches. Use * for patterns: \"ticket-*\" or \"*\" (catch-all). Patterns can only receive.", "example": "info" }, "can_send": { "type": "boolean", "default": true, "description": "Default: true when the platform sends email, else false" }, "can_receive": { "type": "boolean", "default": true }, "webhook_url": { "type": [ "string", "null" ], "description": "Send this address's mail to its own webhook; null/empty = the domain's or account's" }, "require_signed_tag": { "type": "boolean", "description": "Only accept signed reply addresses (support+tag.signature@); plain and forged sub-addresses are refused" }, "parser_id": { "type": [ "string", "null" ], "description": "Parser (from the dashboard's Parsers page) for this address's mail; null for none" } } }, "AddressUpdate": { "type": "object", "additionalProperties": false, "properties": { "can_send": { "type": "boolean" }, "can_receive": { "type": "boolean" }, "webhook_url": { "type": [ "string", "null" ], "description": "Send this address's mail to its own webhook; null/empty = the domain's or account's" }, "require_signed_tag": { "type": "boolean", "description": "Only accept signed reply addresses (support+tag.signature@); plain and forged sub-addresses are refused" }, "parser_id": { "type": [ "string", "null" ], "description": "Parser (from the dashboard's Parsers page) for this address's mail; null for none" } } }, "DomainCreate": { "type": "object", "required": [ "name" ], "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 253, "example": "customer-shop.com" }, "reference": { "type": [ "string", "null" ], "maxLength": 255, "description": "Your own ID for this domain" }, "inbound_enabled": { "type": "boolean", "default": false }, "webhook_url": { "type": [ "string", "null" ], "format": "uri", "description": "Overrides the account's webhook URL for this domain" }, "max_message_bytes": { "type": [ "integer", "null" ], "description": "Largest email accepted for this domain (1024 up to the platform limit, 25 MB); null = platform limit" }, "addresses": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/AddressCreate" } } } }, "DomainUpdate": { "type": "object", "additionalProperties": false, "properties": { "inbound_enabled": { "type": "boolean" }, "webhook_url": { "type": [ "string", "null" ], "format": "uri", "description": "null = use the account's webhook URL" }, "reference": { "type": [ "string", "null" ], "maxLength": 255 }, "max_message_bytes": { "type": [ "integer", "null" ], "description": "Largest email accepted for this domain (1024 up to the platform limit, 25 MB); null = platform limit" } } }, "DnsRecord": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "spf", "dkim", "dmarc", "mx" ] }, "type": { "type": "string", "enum": [ "TXT", "MX" ] }, "host": { "type": "string" }, "value": { "type": "string" }, "priority": { "type": "integer" }, "purpose": { "type": "string" }, "note": { "type": "string" }, "verified": { "type": "boolean" } } }, "DomainAddress": { "type": "object", "properties": { "id": { "type": "string" }, "address": { "type": "string", "format": "email" }, "local_part": { "type": "string" }, "is_pattern": { "type": "boolean" }, "can_send": { "type": "boolean" }, "can_receive": { "type": "boolean" }, "webhook_url": { "type": [ "string", "null" ] }, "require_signed_tag": { "type": "boolean" }, "parser_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Domain": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "reference": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "inbound_enabled": { "type": "boolean" }, "webhook_url": { "type": [ "string", "null" ] }, "max_message_bytes": { "type": [ "integer", "null" ] }, "sending_ready": { "type": "boolean" }, "inbound_ready": { "type": "boolean" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/DnsRecord" } }, "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/DomainAddress" } }, "sender_rules": { "type": "array", "items": { "$ref": "#/components/schemas/SenderRule" } } } }, "VerifyResult": { "type": "object", "properties": { "domain": { "$ref": "#/components/schemas/Domain" }, "checks": { "type": "object", "properties": { "spf": { "type": "object", "properties": { "ok": { "type": "boolean" }, "found": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string" } } }, "dkim": { "type": "object", "properties": { "ok": { "type": "boolean" }, "found": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string" } } }, "dmarc": { "type": "object", "properties": { "ok": { "type": "boolean" }, "found": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string" } } }, "mx": { "type": "object", "properties": { "ok": { "type": "boolean" }, "found": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string" } } } } } } }, "InboundRecipient": { "type": "object", "properties": { "address": { "type": "string", "example": "support+t42.k3j9x2m4q8a7b@acme.com" }, "base_address": { "type": "string", "example": "support@acme.com", "description": "The allow-listed address it was delivered to (sub-address removed)" }, "tag": { "type": [ "string", "null" ], "example": "t42", "description": "The part after +; for a signed reply address, just the tag" }, "tag_verified": { "type": [ "boolean", "null" ], "description": "true: a signed reply address made by your account. false: signed form but wrong signature (forged). null: not a signed tag." } } }, "Bounce": { "type": "object", "properties": { "recipient": { "type": [ "string", "null" ], "description": "The address that couldn't be delivered to" }, "action": { "type": [ "string", "null" ], "example": "failed" }, "status": { "type": [ "string", "null" ], "example": "5.1.1", "description": "5.x.x permanent, 4.x.x temporary" }, "diagnostic": { "type": [ "string", "null" ], "example": "550 5.1.1 User unknown" }, "original_message_id": { "type": [ "string", "null" ], "description": "Message-ID of the email that bounced, when the report includes it" } } }, "CalendarEvent": { "type": "object", "properties": { "method": { "type": [ "string", "null" ], "example": "REQUEST", "description": "REQUEST (invite/update), CANCEL, REPLY (an RSVP), PUBLISH" }, "uid": { "type": [ "string", "null" ] }, "sequence": { "type": [ "integer", "null" ] }, "status": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "start": { "type": [ "string", "null" ], "example": "2026-10-05T09:00:00", "description": "ISO 8601. Ends in Z for UTC; otherwise local to timezone. Date only for all-day events." }, "end": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ], "example": "Europe/London" }, "all_day": { "type": "boolean" }, "recurrence": { "type": [ "string", "null" ], "description": "RRULE, e.g. FREQ=WEEKLY;BYDAY=MO" }, "organizer": { "oneOf": [ { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "attendees": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "example": "NEEDS-ACTION" }, "role": { "type": [ "string", "null" ] } } } } } }, "SpamResult": { "type": "object", "description": "From rspamd, when the platform has spam scanning on", "properties": { "score": { "type": "number", "example": 2.4, "description": "Higher is spammier: around 6 is probably spam, 15 definitely" }, "action": { "type": "string", "example": "no action" }, "symbols": { "type": "array", "items": { "type": "string" }, "description": "Rules that matched" } } }, "VirusResult": { "type": "object", "description": "From ClamAV, when the platform has virus scanning on", "properties": { "infected": { "type": "boolean" }, "names": { "type": "array", "items": { "type": "string" } } } }, "SenderRule": { "type": "object", "properties": { "id": { "type": "string", "example": "rul_…" }, "action": { "type": "string", "enum": [ "allow", "block" ] }, "pattern": { "type": "string", "example": "*.example.com", "description": "An address, a domain, or *. plus a domain for its subdomains" }, "created_at": { "type": "string", "format": "date-time" } } }, "SenderRuleCreate": { "type": "object", "required": [ "action", "pattern" ], "properties": { "action": { "type": "string", "enum": [ "allow", "block" ], "description": "block refuses matching senders. Any allow rule means only matching, authenticated senders are accepted." }, "pattern": { "type": "string", "example": "partner.example" } } }, "ReplyAddressRequest": { "type": "object", "required": [ "address", "tag" ], "properties": { "address": { "type": "string", "example": "support@acme.com", "description": "A receiving address on one of your domains" }, "tag": { "type": "string", "example": "t42", "description": "1-40 characters: letters, digits, - and _. Lower-cased." } } }, "ReplyAddress": { "type": "object", "properties": { "address": { "type": "string", "example": "support+t42.k3j9x2m4q8a7b@acme.com" }, "base_address": { "type": "string" }, "tag": { "type": "string" } } }, "Delivery": { "type": "object", "description": "What happened to one inbound email for your account. Metadata only, never content.", "properties": { "id": { "type": "integer" }, "domain_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "delivered", "deferred", "failed", "rejected", "dropped" ], "description": "deferred: your webhook failed temporarily, the sender will retry. failed: your webhook refused it (4xx). rejected: refused by a rule or unknown address. dropped: accepted but not delivered (auto-reply setting)." }, "reason": { "type": [ "string", "null" ] }, "email_id": { "type": [ "string", "null" ] }, "event_id": { "type": [ "string", "null" ] }, "message_id": { "type": [ "string", "null" ] }, "sender_domain": { "type": [ "string", "null" ] }, "recipients": { "type": "array", "items": { "type": "string" } }, "webhook_host": { "type": [ "string", "null" ] }, "http_status": { "type": [ "integer", "null" ] }, "attempts": { "type": [ "integer", "null" ] }, "duration_ms": { "type": [ "integer", "null" ] }, "size_bytes": { "type": [ "integer", "null" ] }, "spam_score": { "type": [ "number", "null" ] }, "flags": { "type": [ "object", "null" ], "description": "e.g. dmarc, auto_submitted, virus, signed_tag, and code for refusals" }, "created_at": { "type": "string", "format": "date-time" } } }, "Extracted": { "type": "object", "properties": { "parser_id": { "type": "string", "example": "prs_…" }, "parser": { "type": "string", "example": "Orders" }, "method": { "type": "string", "enum": [ "rules", "ai" ] }, "fields": { "type": "object", "additionalProperties": true, "example": { "order_number": "1042", "total": 42.5, "tracking": "TRK-88213" }, "description": "One key per field you defined; null when the email didn't contain it. Empty when extraction failed." }, "error": { "type": [ "string", "null" ], "description": "Why extraction failed (the email is still delivered), e.g. the daily AI limit" }, "truncated": { "type": "boolean", "description": "AI parsers: the email was very long and only its start was read" } } }, "Inbox": { "type": "object", "properties": { "address": { "type": [ "string", "null" ], "example": "k3j9x2m4q8a7@in.mailparser.example", "description": "null when turned off" }, "enabled": { "type": "boolean" }, "available": { "type": "boolean", "description": "false when this platform has no instant addresses" } } }, "SampleResult": { "type": "object", "properties": { "to": { "type": "string" }, "delivered": { "type": "boolean" }, "error": { "type": "string", "description": "Only when not delivered" } } }, "Thread": { "type": "object", "description": "The conversation this email belongs to. thread_id is the same for the first message and every reply (derived from References / In-Reply-To, then Outlook's Thread-Index), so it can be computed for an email you sent: thr_ + the first 24 hex characters of SHA-256 of its Message-ID without angle brackets (domain part lower-cased). The SDKs have a helper.", "required": [ "id", "root_message_id", "position", "is_reply", "method", "tag" ], "properties": { "id": { "type": "string", "example": "thr_836de45f552c568b8e3b9810" }, "root_message_id": { "type": [ "string", "null" ], "example": "", "description": "The conversation's first message; null when only Outlook's Thread-Index identified it" }, "position": { "type": "integer", "description": "0 for the first message; otherwise how many messages precede it (approximate)" }, "is_reply": { "type": "boolean" }, "method": { "type": "string", "enum": [ "references", "in_reply_to", "thread_index", "message_id", "none" ] }, "tag": { "type": [ "string", "null" ], "description": "Your tag from a verified signed reply address (e.g. a ticket ID), when there is one" } } }, "WebhookSettings": { "type": "object", "properties": { "webhook_url": { "type": [ "string", "null" ], "format": "uri" }, "backup_webhook_url": { "type": [ "string", "null" ], "format": "uri", "description": "Tried when webhook_url is unreachable or returns 5xx (after its retries), before the sender is asked to retry. A 4xx answer is final." }, "webhook_signature": { "type": "string", "enum": [ "standard", "legacy" ], "description": "standard = Standard Webhooks; legacy = the original t=…,v1=… format. Switching to standard needs a secret made after Standard Webhooks support (rotate first if you get secret_incompatible)." }, "reject_bulk_inbound": { "type": "boolean" }, "enforce_dmarc": { "type": "boolean" }, "drop_auto_replies": { "type": "boolean" }, "spam_threshold": { "type": [ "number", "null" ] }, "reject_viruses": { "type": "boolean" }, "attachments_mode": { "type": "string", "enum": [ "inline", "multipart", "omit" ] }, "include_raw": { "type": "boolean" }, "alerts_enabled": { "type": "boolean" }, "webhook_secret_rotating_until": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookSettingsUpdate": { "type": "object", "description": "Only the settings to change.", "properties": { "webhook_url": { "type": [ "string", "null" ], "format": "uri" }, "backup_webhook_url": { "type": [ "string", "null" ], "format": "uri", "description": "Tried when webhook_url is unreachable or returns 5xx (after its retries), before the sender is asked to retry. A 4xx answer is final." }, "webhook_signature": { "type": "string", "enum": [ "standard", "legacy" ], "description": "standard = Standard Webhooks; legacy = the original t=…,v1=… format. Switching to standard needs a secret made after Standard Webhooks support (rotate first if you get secret_incompatible)." }, "reject_bulk_inbound": { "type": "boolean" }, "enforce_dmarc": { "type": "boolean" }, "drop_auto_replies": { "type": "boolean" }, "spam_threshold": { "type": [ "number", "null" ] }, "reject_viruses": { "type": "boolean" }, "attachments_mode": { "type": "string", "enum": [ "inline", "multipart", "omit" ] }, "include_raw": { "type": "boolean" }, "alerts_enabled": { "type": "boolean" } } }, "SecretRotation": { "type": "object", "properties": { "webhook_secret": { "type": "string", "example": "whsec_Rml4dHVyZVNlY3JldEZvclNES1Rlc3RzMDE=" }, "previous_secret_valid_until": { "type": [ "string", "null" ], "format": "date-time" } } }, "Subaccount": { "type": "object", "properties": { "id": { "type": "string", "example": "acct_mb_kwrlaq_jhk2AQ" }, "name": { "type": "string" }, "reference": { "type": [ "string", "null" ], "description": "Your own ID for this customer" }, "suspended": { "type": "boolean" }, "suspended_at": { "type": [ "string", "null" ], "format": "date-time" }, "webhook_url": { "type": [ "string", "null" ] }, "domains": { "type": "integer" }, "users": { "type": "integer" }, "delivered_30d": { "type": "integer" }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "Invitation": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "developer", "viewer" ] }, "expires_at": { "type": "string", "format": "date-time" } } }, "SubaccountCreated": { "type": "object", "properties": { "id": { "type": "string", "example": "acct_mb_kwrlaq_jhk2AQ" }, "name": { "type": "string" }, "reference": { "type": [ "string", "null" ], "description": "Your own ID for this customer" }, "suspended": { "type": "boolean" }, "suspended_at": { "type": [ "string", "null" ], "format": "date-time" }, "webhook_url": { "type": [ "string", "null" ] }, "domains": { "type": "integer" }, "users": { "type": "integer" }, "delivered_30d": { "type": "integer" }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "webhook_secret": { "type": "string", "description": "Its webhook signing secret: shown only this once" }, "invitation": { "oneOf": [ { "$ref": "#/components/schemas/Invitation" }, { "type": "null" } ] } } }, "SubaccountCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "reference": { "type": [ "string", "null" ], "maxLength": 255 }, "webhook_url": { "type": [ "string", "null" ], "format": "uri" }, "owner_email": { "type": [ "string", "null" ], "format": "email", "description": "Invite this person (by email, with your branding) to use the dashboard as the owner" } } }, "SubaccountUpdate": { "type": "object", "properties": { "name": { "type": "string" }, "reference": { "type": [ "string", "null" ] }, "suspended": { "type": "boolean", "description": "Suspended: its mail is refused, users are signed out and its own API keys stop working. You can still manage it." } } }, "InvitationCreate": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "owner", "admin", "developer", "viewer" ], "default": "owner" } } }, "Meta": { "type": "object", "properties": { "webhook_source_ips": { "type": "array", "items": { "type": "string" }, "description": "Webhooks come from these addresses (empty if not published)" }, "mx_hostname": { "type": "string" }, "inbox_domain": { "type": [ "string", "null" ] }, "data_region": { "type": [ "string", "null" ], "example": "United Kingdom" }, "webhook_signature": { "type": "object", "properties": { "default": { "type": "string" }, "spec": { "type": "string" } } } } }, "Usage": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "false when this platform has no paid plans (nothing is limited by plan)" }, "plan": { "type": "string", "enum": [ "free", "starter", "pro", "business" ] }, "plan_name": { "type": "string" }, "interval": { "type": [ "string", "null" ], "enum": [ "month", "year", null ] }, "override": { "type": "boolean", "description": "Plan set by the platform operator" }, "billing_account_id": { "type": "string", "description": "The account billed (a reseller, for its sub-accounts)" }, "period_start": { "type": "string", "format": "date-time" }, "period_end": { "type": "string", "format": "date-time" }, "emails": { "type": "object", "properties": { "used": { "type": "integer" }, "included": { "type": "integer" }, "overage": { "type": "integer" } } }, "ai": { "type": "object", "properties": { "used": { "type": "integer" }, "included": { "type": "integer" } } }, "overage_pence_per_1000": { "type": [ "integer", "null" ] }, "overage_cost_pence": { "type": "integer" } } }, "Me": { "type": "object", "required": [ "account", "api_key", "platform" ], "properties": { "account": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "plan": { "type": [ "string", "null" ] } } }, "api_key": { "type": "object", "properties": { "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "send", "domains", "accounts", "integrations" ] } } } }, "reseller_id": { "type": "string", "description": "Set when a reseller's key acts on a sub-account" }, "platform": { "type": "string" } } }, "HookCreate": { "type": "object", "required": [ "target_url" ], "properties": { "target_url": { "type": "string", "format": "uri" }, "event": { "type": "string", "enum": [ "email.received" ] }, "source": { "type": "string", "enum": [ "zapier", "make", "n8n", "webhook" ], "default": "webhook" }, "name": { "type": "string", "maxLength": 100 }, "filter": { "type": [ "object", "null" ], "properties": { "address": { "type": "string", "description": "Only email to addresses matching this; * and ? wildcards" } } } } }, "HookCreated": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "type": "string" }, "target_url": { "type": "string" }, "source": { "type": "string" }, "filter": { "type": [ "object", "null" ], "properties": { "address": { "type": "string", "description": "Only email to addresses matching this; * and ? wildcards" } } }, "created_at": { "type": "string", "format": "date-time" } } }, "Hook": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "type": "string" }, "source": { "type": "string" }, "name": { "type": "string" }, "target": { "type": "string", "description": "The URL's host only" }, "filter": { "type": [ "object", "null" ], "properties": { "address": { "type": "string", "description": "Only email to addresses matching this; * and ? wildcards" } } }, "created_at": { "type": "string", "format": "date-time" } } }, "DestinationCreate": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "webhook", "slack", "teams", "google_sheets", "zapier", "make", "n8n" ] }, "name": { "type": "string", "maxLength": 100 }, "enabled": { "type": "boolean", "default": true }, "all_mail": { "type": "boolean", "default": false, "description": "Get every email (else only what routing rules send)" }, "filter": { "type": [ "object", "null" ], "properties": { "address": { "type": "string", "description": "Only email to addresses matching this; * and ? wildcards" } } }, "url": { "type": "string", "description": "Slack/Teams/webhook URL, or the Apps Script web app URL" }, "include_body": { "type": "boolean", "default": true, "description": "Slack and Teams: include the message text" }, "mode": { "type": "string", "enum": [ "service_account", "apps_script" ], "description": "Google Sheets" }, "spreadsheet": { "type": "string", "description": "Google Sheets (service_account): the spreadsheet URL or id" }, "sheet": { "type": "string", "description": "Google Sheets: the tab" }, "columns": { "type": "array", "items": { "type": "string" }, "maxItems": 30, "description": "Google Sheets columns, e.g. received_at, from, subject, extracted.order_number" } } }, "DestinationUpdate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "enabled": { "type": "boolean", "default": true }, "all_mail": { "type": "boolean", "default": false, "description": "Get every email (else only what routing rules send)" }, "filter": { "type": [ "object", "null" ], "properties": { "address": { "type": "string", "description": "Only email to addresses matching this; * and ? wildcards" } } }, "url": { "type": "string", "description": "Slack/Teams/webhook URL, or the Apps Script web app URL" }, "include_body": { "type": "boolean", "default": true, "description": "Slack and Teams: include the message text" }, "mode": { "type": "string", "enum": [ "service_account", "apps_script" ], "description": "Google Sheets" }, "spreadsheet": { "type": "string", "description": "Google Sheets (service_account): the spreadsheet URL or id" }, "sheet": { "type": "string", "description": "Google Sheets: the tab" }, "columns": { "type": "array", "items": { "type": "string" }, "maxItems": 30, "description": "Google Sheets columns, e.g. received_at, from, subject, extracted.order_number" } } }, "Destination": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "webhook", "slack", "teams", "google_sheets", "zapier", "make", "n8n" ] }, "name": { "type": "string" }, "summary": { "type": [ "string", "null" ], "description": "Host or spreadsheet name; never the full URL" }, "enabled": { "type": "boolean" }, "all_mail": { "type": "boolean" }, "filter": { "type": [ "object", "null" ], "properties": { "address": { "type": "string", "description": "Only email to addresses matching this; * and ? wildcards" } } }, "source": { "type": "string", "enum": [ "dashboard", "api", "hook" ] }, "settings": { "type": "object", "description": "Non-secret settings: include_body; for Sheets mode, spreadsheet_id, sheet, columns" }, "health": { "type": "object", "properties": { "status": { "type": [ "string", "null" ], "enum": [ "ok", "failing", null ] }, "error": { "type": [ "string", "null" ] }, "last_delivery_at": { "type": [ "string", "null" ] }, "failing_since": { "type": [ "string", "null" ] } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RoutingCondition": { "type": "object", "required": [ "field", "op" ], "properties": { "field": { "type": "string", "enum": [ "subject", "from", "from_domain", "from_name", "to", "cc", "body", "attachment_name", "has_attachments", "spam_score", "header" ] }, "op": { "type": "string", "enum": [ "contains", "not_contains", "equals", "not_equals", "starts_with", "ends_with", "matches", "not_matches", "gte", "lt", "is_true", "is_false" ] }, "value": { "type": [ "string", "number" ] }, "header": { "type": "string", "description": "For field header: the header name" } } }, "RoutingRuleCreate": { "type": "object", "required": [ "name", "conditions", "action" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "enabled": { "type": "boolean", "default": true }, "domain_id": { "type": [ "string", "null" ], "description": "Only mail to this domain; null for all" }, "match": { "type": "string", "enum": [ "all", "any" ], "default": "all" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingCondition" }, "minItems": 1, "maxItems": 10 }, "action": { "type": "string", "enum": [ "route", "copy", "drop" ] }, "targets": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "description": "Destination ids, or \"webhook\" for the usual webhook (route only)" }, "position": { "type": "integer", "minimum": 1, "description": "Where in the list (1 = first); default last" } } }, "RoutingRuleUpdate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "enabled": { "type": "boolean", "default": true }, "domain_id": { "type": [ "string", "null" ], "description": "Only mail to this domain; null for all" }, "match": { "type": "string", "enum": [ "all", "any" ], "default": "all" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingCondition" }, "minItems": 1, "maxItems": 10 }, "action": { "type": "string", "enum": [ "route", "copy", "drop" ] }, "targets": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "description": "Destination ids, or \"webhook\" for the usual webhook (route only)" }, "position": { "type": "integer", "minimum": 1, "description": "Where in the list (1 = first); default last" } } }, "RoutingRule": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "position": { "type": "integer" }, "domain_id": { "type": [ "string", "null" ] }, "match": { "type": "string", "enum": [ "all", "any" ] }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingCondition" } }, "action": { "type": "string", "enum": [ "route", "copy", "drop" ] }, "targets": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RuleTest": { "type": "object", "properties": { "subject": { "type": "string" }, "from": { "type": "string" }, "from_name": { "type": "string" }, "to": { "type": "string" }, "body": { "type": "string" }, "attachment_names": { "type": "array", "items": { "type": "string" } }, "spam_score": { "type": "number" } } }, "RoutingDecision": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "default", "route", "drop" ] }, "targets": { "type": "array", "items": { "type": "string" } }, "copies": { "type": "array", "items": { "type": "string" } }, "matched": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "action": { "type": "string" } } } } } } }, "parameters": { "AccountHeader": { "name": "Email-Parser-Account", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Resellers: act on one of your sub-accounts (acct_…). Needs a key with the accounts permission; the request then uses the key's other permissions on that sub-account." } } } }