{ "openapi": "3.1.0", "info": { "title": "Webdock Mail API", "version": "1.0.0", "description": "Transactional Mail. Accepted means provider acceptance, not delivery. JSON limit 4,000,000 bytes; text+HTML 512 KiB. Requests 120/minute/tenant. Unknown handoffs must never be resent with a new key. Webhooks: HMAC-SHA256 over id.timestamp.rawBody, at-least-once." }, "servers": [ { "url": "https://api.webdock.dev/api/mail/v1" } ], "paths": { "/emails": { "get": { "operationId": "emails_list", "summary": "List emails", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor returned as nextCursor" }, { "name": "domain_id", "in": "query", "schema": { "$ref": "#/components/schemas/ID" } }, { "name": "include_simulated", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Emails" ] }, "post": { "operationId": "emails_send", "summary": "Send an email", "description": "Requires sending_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Completed responses replay for 24 hours. Unknown handoffs remain reserved until reconciliation; never retry with a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendResult" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Emails" ] } }, "/emails/batch": { "post": { "operationId": "emails_batch", "summary": "Send a batch", "description": "Requires sending_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Completed responses replay for 24 hours. Unknown handoffs remain reserved until reconciliation; never retry with a new key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "from", "to", "subject" ], "additionalProperties": false, "properties": { "from": { "type": "string" }, "to": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 50 } ] }, "cc": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 50 } ] }, "bcc": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 50 } ] }, "reply_to": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 50 } ] }, "subject": { "type": "string", "description": "At most 998 UTF-8 bytes, no line breaks" }, "text": { "type": "string" }, "html": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "maxProperties": 50 }, "tags": { "type": "array", "maxItems": 50, "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" }, "value": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" } } } } } } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } }, "202": { "description": "Durable batch still processing; poll with a Full key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Emails" ] } }, "/emails/{id}": { "get": { "operationId": "emails_get", "summary": "Retrieve an email", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ID" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Emails" ] }, "patch": { "operationId": "emails_reschedule", "summary": "Reschedule an email", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ID" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Current message revision; absent: 428, stale: 409" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled_at": { "type": "string", "format": "date-time" } }, "required": [ "scheduled_at" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Emails" ] } }, "/emails/{id}/cancel": { "post": { "operationId": "emails_cancel", "summary": "Cancel an email", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ID" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Current message revision; absent: 428, stale: 409" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Emails" ] } }, "/batches/{id}": { "get": { "operationId": "batches_get", "summary": "Retrieve a batch", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ID" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Batches" ] } }, "/domains": { "get": { "operationId": "domains_list", "summary": "List domains", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor returned as nextCursor" }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Domains" ] }, "post": { "operationId": "domains_create", "summary": "Add a domain", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Domains" ] } }, "/domains/{id}": { "get": { "operationId": "domains_get", "summary": "Retrieve a domain", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ID" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Domains" ] }, "delete": { "operationId": "domains_delete", "summary": "Remove a domain", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ID" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Domains" ] } }, "/domains/{id}/verify": { "post": { "operationId": "domains_verify", "summary": "Verify a domain", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ID" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Domains" ] } }, "/api-keys": { "get": { "operationId": "keys_list", "summary": "List API keys", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor returned as nextCursor" }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "API keys" ] }, "post": { "operationId": "keys_create", "summary": "Create an API key", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 80 }, "permission": { "enum": [ "sending_access", "full_access" ] }, "domain_id": { "$ref": "#/components/schemas/ID" } }, "required": [ "name", "permission" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "API keys" ] } }, "/api-keys/{id}": { "delete": { "operationId": "keys_delete", "summary": "Revoke an API key", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ID" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "API keys" ] } }, "/webhooks": { "get": { "operationId": "webhooks_list", "summary": "List webhooks", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor returned as nextCursor" }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Webhooks" ] }, "post": { "operationId": "webhooks_create", "summary": "Create a webhook", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/EventType" } } }, "required": [ "url", "events" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Webhooks" ] } }, "/webhooks/{id}": { "get": { "operationId": "webhooks_get", "summary": "Retrieve a webhook", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ID" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Webhooks" ] }, "patch": { "operationId": "webhooks_update", "summary": "Update a webhook", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ID" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/EventType" } }, "enabled": { "type": "boolean" } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Webhooks" ] }, "delete": { "operationId": "webhooks_delete", "summary": "Delete a webhook", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ID" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Webhooks" ] } }, "/webhooks/{id}/deliveries": { "get": { "operationId": "webhooks_deliveries", "summary": "List webhook deliveries", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ID" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor returned as nextCursor" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Webhooks" ] } }, "/webhooks/{id}/rotate": { "post": { "operationId": "webhooks_rotate", "summary": "Rotate a signing secret", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ID" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Webhooks" ] } }, "/webhooks/{id}/deliveries/{deliveryID}/replay": { "post": { "operationId": "webhooks_replay", "summary": "Replay a delivery", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ID" } }, { "name": "deliveryID", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ID" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Webhooks" ] } }, "/suppressions": { "get": { "operationId": "suppressions_list", "summary": "List suppressions", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor returned as nextCursor" }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Suppressions" ] }, "post": { "operationId": "suppressions_create", "summary": "Add a suppression", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "reason": { "enum": [ "manual", "bounced", "complained", "unsubscribed" ] } }, "required": [ "email" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Suppressions" ] } }, "/suppressions/{email}": { "delete": { "operationId": "suppressions_delete", "summary": "Remove a suppression", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Address" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Suppressions" ] } }, "/logs": { "get": { "operationId": "logs_list", "summary": "List request logs", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor returned as nextCursor" }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "method", "in": "query", "schema": { "type": "string", "enum": [ "GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS" ] } }, { "name": "status", "in": "query", "schema": { "type": "integer" }, "description": "HTTP status, or 0 for an unfinished request" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Logs" ] } }, "/logs/{id}": { "get": { "operationId": "logs_get", "summary": "Retrieve a request log", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ID" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Logs" ] } }, "/analytics": { "get": { "operationId": "analytics_get", "summary": "Retrieve analytics", "description": "Requires full_access. Account and connection are derived from the key.", "security": [ { "MailApiKey": [] } ], "parameters": [ { "name": "domain_id", "in": "query", "schema": { "$ref": "#/components/schemas/ID" } }, { "name": "include_simulated", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "days", "in": "query", "schema": { "type": "integer", "enum": [ 7, 30, 90 ], "default": 30 } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Failed or uncertain handoff. Inspect email_id; never automatically resend.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Request rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Analytics" ] } } }, "components": { "securitySchemes": { "MailApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "wdm_…" } }, "schemas": { "ID": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "Address": { "type": "string" }, "EventType": { "enum": [ "email.scheduled", "email.canceled", "email.sent", "email.delivered", "email.delivery_delayed", "email.opened", "email.clicked", "email.bounced", "email.complained", "email.unsubscribed", "email.failed", "email.suppressed", "domain.created", "domain.updated", "domain.deleted" ] }, "SendResult": { "type": "object", "required": [ "id" ], "properties": { "id": { "$ref": "#/components/schemas/ID" } } }, "Batch": { "type": "object", "required": [ "id", "status", "data" ], "properties": { "id": { "type": "string" }, "status": { "enum": [ "processing", "succeeded", "failed" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SendResult" } }, "failed_index": { "type": "integer" }, "failed_email_id": { "type": [ "string", "null" ] } } }, "Page": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object" } }, "nextCursor": { "type": [ "string", "null" ] } } }, "Error": { "type": "object", "required": [ "statusCode", "name", "message", "request_id" ], "properties": { "statusCode": { "type": "integer" }, "name": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "email_id": { "type": "string" }, "id": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SendResult" } }, "failed_index": { "type": "integer" }, "failed_email_id": { "type": [ "string", "null" ] } } }, "Email": { "type": "object", "required": [ "from", "to", "subject" ], "additionalProperties": false, "properties": { "from": { "type": "string" }, "to": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 50 } ] }, "cc": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 50 } ] }, "bcc": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 50 } ] }, "reply_to": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 50 } ] }, "subject": { "type": "string", "description": "At most 998 UTF-8 bytes, no line breaks" }, "text": { "type": "string" }, "html": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "maxProperties": 50 }, "tags": { "type": "array", "maxItems": 50, "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" }, "value": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" } } } }, "attachments": { "type": "array", "maxItems": 10, "description": "At most 2 MiB decoded; no URL/path attachments", "items": { "type": "object", "required": [ "content" ], "additionalProperties": false, "properties": { "content": { "type": "string", "contentEncoding": "base64" }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "content_id": { "type": "string", "description": "CID local part. The verified Turbo transport appends @sender-domain; reference cid:@ in HTML." } } } }, "scheduled_at": { "type": "string", "format": "date-time" } } } } } }