{ "openapi": "3.1.0", "info": { "title": "Dash Mail API", "version": "1.0.0", "description": "Private, programmable email on dash.limited. Create inboxes, receive and send mail, retrieve attachments, and subscribe to signed webhooks." }, "servers": [ { "url": "https://mail.dash.limited/v1" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Use a dm_live_ API key. Account keys manage everything; inbox keys can only access the assigned inbox." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } } } } }, "Message": { "type": "object", "properties": { "id": { "type": "string" }, "inbox_id": { "type": "string" }, "thread_id": { "type": "string" }, "direction": { "enum": [ "inbound", "outbound" ] }, "status": { "enum": [ "processing", "received", "sending", "sent", "failed" ] }, "from": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" }, "preview": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" } } } } }, "paths": { "/inboxes": { "get": { "tags": [ "Inboxes" ], "summary": "List inboxes", "description": "Returns up to 100 inboxes, newest first. An inbox-scoped key only sees its own inbox.", "operationId": "get__inboxes", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "data": [ { "id": "inb_a1b2c3", "email": "research@dash.limited", "name": "Research agent", "active": true, "created_at": "2026-10-05T09:00:00.000Z" } ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } }, "post": { "tags": [ "Inboxes" ], "summary": "Create an inbox", "description": "Create an address on dash.limited. Mail is accepted as soon as the inbox exists. Requires an account key.", "operationId": "post__inboxes", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "inb_a1b2c3", "email": "research@dash.limited", "name": "Research agent", "active": true, "created_at": "2026-10-05T09:00:00.000Z" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "username" ], "properties": { "username": { "type": "string", "description": "Lowercase letters, digits, dots, underscores and hyphens. Start and end with a letter or digit. Maximum 64 characters." }, "name": { "type": "string", "description": "Optional display name. Maximum 100 bytes." } } }, "example": { "username": "research", "name": "Research agent" } } } } } }, "/inboxes/{inbox_id}": { "get": { "tags": [ "Inboxes" ], "summary": "Get an inbox", "description": "Retrieve an inbox by ID.", "operationId": "get__inboxes__inbox_id_", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Inbox ID returned when creating an inbox." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "inb_a1b2c3", "email": "research@dash.limited", "name": "Research agent", "active": true, "created_at": "2026-10-05T09:00:00.000Z" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } }, "patch": { "tags": [ "Inboxes" ], "summary": "Update an inbox", "description": "Rename an inbox or enable/disable it. Disabled inboxes reject incoming mail and cannot send. Account key required.", "operationId": "patch__inboxes__inbox_id_", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Inbox ID returned when creating an inbox." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "inb_a1b2c3", "email": "research@dash.limited", "name": "Research agent", "active": true, "created_at": "2026-10-05T09:00:00.000Z" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name. Maximum 100 bytes." }, "active": { "type": "boolean", "description": "Enable or disable sending and receiving for this address." } } }, "example": { "name": "Research agent", "active": true } } } } }, "delete": { "tags": [ "Inboxes" ], "summary": "Disable an inbox", "description": "Soft-disable an address while retaining messages, attachments and history. Re-enable using PATCH. Account key required.", "operationId": "delete__inboxes__inbox_id_", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Inbox ID returned when creating an inbox." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "inb_a1b2c3", "active": false } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } } }, "/inboxes/{inbox_id}/messages": { "get": { "tags": [ "Messages" ], "summary": "List messages", "description": "Newest first, with stable cursor pagination. Includes incoming and outgoing mail. Fetch a message to retrieve its complete body.", "operationId": "get__inboxes__inbox_id__messages", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Inbox ID returned when creating an inbox." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Number of messages to return." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque next_cursor returned by the previous page." }, { "name": "direction", "in": "query", "schema": { "enum": [ "inbound", "outbound" ] }, "description": "Filter by incoming or outgoing mail." }, { "name": "label", "in": "query", "schema": { "type": "string" }, "description": "Filter by an exact label, such as unread." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "data": [ { "id": "msg_d4e5f6", "inbox_id": "inb_a1b2c3", "thread_id": "thr_123abc", "direction": "inbound", "status": "received", "message_id": "", "from": "alex@example.com", "to": [ "research@dash.limited" ], "cc": [], "subject": "A quick question", "preview": "Could you help me find…", "labels": [ "unread" ], "in_reply_to": null, "created_at": "2026-10-05T09:01:00.000Z", "error": null } ], "next_cursor": null } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } }, "post": { "tags": [ "Messages" ], "summary": "Send a message", "description": "Send from this inbox to up to 50 recipients. A sent status means accepted by the sending service; it is not a delivery or read receipt. Use an Idempotency-Key for safe retries.", "operationId": "post__inboxes__inbox_id__messages", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Inbox ID returned when creating an inbox." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Unique key (1–128 characters) for each logical send. Reuse the same key and payload to retrieve the stored result without sending again." } ], "responses": { "200": { "description": "Previously stored idempotent result", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "msg_d4e5f6", "inbox_id": "inb_a1b2c3", "thread_id": "thr_123abc", "direction": "outbound", "status": "sent", "message_id": "", "from": "research@dash.limited", "to": [ "alex@example.com" ], "cc": [], "subject": "A quick question", "preview": "Could you help me find…", "labels": [], "in_reply_to": null, "created_at": "2026-10-05T09:01:00.000Z", "error": null } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "msg_d4e5f6", "inbox_id": "inb_a1b2c3", "thread_id": "thr_123abc", "direction": "outbound", "status": "sent", "message_id": "", "from": "research@dash.limited", "to": [ "alex@example.com" ], "cc": [], "subject": "A quick question", "preview": "Could you help me find…", "labels": [], "in_reply_to": null, "created_at": "2026-10-05T09:01:00.000Z", "error": null } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to", "subject" ], "properties": { "to": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Recipient email addresses. Maximum 50 across to, cc and bcc." }, "subject": { "type": "string", "description": "Subject line, 1–998 bytes without line breaks." }, "text": { "type": "string", "description": "Plain text body. Provide text or html. Maximum 2,000,000 bytes." }, "html": { "type": "string", "description": "HTML body. Provide text or html. Maximum 2,000,000 bytes." }, "cc": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Optional carbon-copy recipients." }, "bcc": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Optional carbon-copy recipients." }, "attachments": { "type": "array", "items": { "type": "object", "required": [ "filename", "content" ], "properties": { "filename": { "type": "string", "description": "File name." }, "content_type": { "type": "string", "description": "MIME type.", "default": "application/octet-stream" }, "content": { "type": "string", "description": "Base64-encoded file contents." } } }, "description": "Up to 32 base64-encoded files. Maximum total request body: 5 MiB." } } }, "example": { "to": [ "alex@example.com" ], "subject": "Hello from Dash Mail", "text": "Your agent has an inbox." } } } } } }, "/inboxes/{inbox_id}/messages/{message_id}": { "get": { "tags": [ "Messages" ], "summary": "Get a message", "description": "Retrieve the message, plain text, HTML and attachment metadata. Content is available once inbound status is received.", "operationId": "get__inboxes__inbox_id__messages__message_id_", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Inbox ID returned when creating an inbox." }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Message ID returned by List messages or Send a message." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "msg_d4e5f6", "inbox_id": "inb_a1b2c3", "thread_id": "thr_123abc", "direction": "inbound", "status": "received", "message_id": "", "from": "alex@example.com", "to": [ "research@dash.limited" ], "cc": [], "subject": "A quick question", "preview": "Could you help me find…", "labels": [ "unread" ], "in_reply_to": null, "created_at": "2026-10-05T09:01:00.000Z", "error": null, "text": "Could you help me find…", "html": "

Could you help me find…

", "attachments": [] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } }, "patch": { "tags": [ "Messages" ], "summary": "Update labels", "description": "Replace the message labels. Use unread, read or your own labels to track agent processing. Up to 20 labels.", "operationId": "patch__inboxes__inbox_id__messages__message_id_", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Inbox ID returned when creating an inbox." }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Message ID returned by List messages or Send a message." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "msg_d4e5f6", "inbox_id": "inb_a1b2c3", "thread_id": "thr_123abc", "direction": "inbound", "status": "received", "message_id": "", "from": "alex@example.com", "to": [ "research@dash.limited" ], "cc": [], "subject": "A quick question", "preview": "Could you help me find…", "labels": [ "read", "processed" ], "in_reply_to": null, "created_at": "2026-10-05T09:01:00.000Z", "error": null } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "labels" ], "properties": { "labels": { "type": "array", "items": { "type": "string" }, "description": "Replace all labels with up to 20 names, each 1–50 bytes. Duplicates are removed." } } }, "example": { "labels": [ "read", "processed" ] } } } } } }, "/inboxes/{inbox_id}/messages/{message_id}/reply": { "post": { "tags": [ "Messages" ], "summary": "Reply to a message", "description": "Reply to a processed inbound message. Uses Reply-To when present, otherwise the original From address. Preserves the thread and adds In-Reply-To and References headers.", "operationId": "post__inboxes__inbox_id__messages__message_id__reply", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Inbox ID returned when creating an inbox." }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Message ID returned by List messages or Send a message." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Unique key (1–128 characters) for each logical send. Reuse the same key and payload to retrieve the stored result without sending again." } ], "responses": { "200": { "description": "Previously stored idempotent result", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "msg_d4e5f6", "inbox_id": "inb_a1b2c3", "thread_id": "thr_123abc", "direction": "outbound", "status": "sent", "message_id": "", "from": "alex@example.com", "to": [ "research@dash.limited" ], "cc": [], "subject": "Re: A quick question", "preview": "Could you help me find…", "labels": [], "in_reply_to": null, "created_at": "2026-10-05T09:01:00.000Z", "error": null } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "msg_d4e5f6", "inbox_id": "inb_a1b2c3", "thread_id": "thr_123abc", "direction": "outbound", "status": "sent", "message_id": "", "from": "alex@example.com", "to": [ "research@dash.limited" ], "cc": [], "subject": "Re: A quick question", "preview": "Could you help me find…", "labels": [], "in_reply_to": null, "created_at": "2026-10-05T09:01:00.000Z", "error": null } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "Plain text body. Provide text or html. Maximum 2,000,000 bytes." }, "html": { "type": "string", "description": "HTML body. Provide text or html. Maximum 2,000,000 bytes." }, "cc": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Optional carbon-copy recipients." }, "bcc": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Optional carbon-copy recipients." }, "attachments": { "type": "array", "items": { "type": "object", "required": [ "filename", "content" ], "properties": { "filename": { "type": "string", "description": "File name." }, "content_type": { "type": "string", "description": "MIME type.", "default": "application/octet-stream" }, "content": { "type": "string", "description": "Base64-encoded file contents." } } }, "description": "Up to 32 base64-encoded files. Maximum total request body: 5 MiB." } } }, "example": { "text": "Absolutely. Here is what I found…" } } } } } }, "/inboxes/{inbox_id}/messages/{message_id}/raw": { "get": { "tags": [ "Messages" ], "summary": "Download raw email", "description": "Download the original .eml file for an inbound message. Returns message/rfc822. Outgoing messages do not have a raw MIME download.", "operationId": "get__inboxes__inbox_id__messages__message_id__raw", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Inbox ID returned when creating an inbox." }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Message ID returned by List messages or Send a message." } ], "responses": { "200": { "description": "Raw RFC 5322 email", "content": { "message/rfc822": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } } }, "/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}": { "get": { "tags": [ "Messages" ], "summary": "Download an attachment", "description": "Download file bytes. Attachment IDs are returned by Get a message. Files are served as downloads, never executed as HTML.", "operationId": "get__inboxes__inbox_id__messages__message_id__attachments__attachment_id_", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Inbox ID returned when creating an inbox." }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Message ID returned by List messages or Send a message." }, { "name": "attachment_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File bytes", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } } }, "/inboxes/{inbox_id}/threads": { "get": { "tags": [ "Threads" ], "summary": "List threads", "description": "Returns up to 100 threads, ordered by the newest message in each conversation.", "operationId": "get__inboxes__inbox_id__threads", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Inbox ID returned when creating an inbox." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "data": [ { "id": "thr_123abc", "message_count": 2, "updated_at": "2026-10-05T09:02:00.000Z" } ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } } }, "/inboxes/{inbox_id}/threads/{thread_id}/messages": { "get": { "tags": [ "Threads" ], "summary": "Get thread messages", "description": "List messages belonging to one conversation. Uses the same filters and cursor pagination as List messages.", "operationId": "get__inboxes__inbox_id__threads__thread_id__messages", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Inbox ID returned when creating an inbox." }, { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Number of messages to return." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque next_cursor returned by the previous page." }, { "name": "direction", "in": "query", "schema": { "enum": [ "inbound", "outbound" ] }, "description": "Filter by incoming or outgoing mail." }, { "name": "label", "in": "query", "schema": { "type": "string" }, "description": "Filter by an exact label, such as unread." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "data": [ { "id": "msg_d4e5f6", "inbox_id": "inb_a1b2c3", "thread_id": "thr_123abc", "direction": "inbound", "status": "received", "message_id": "", "from": "alex@example.com", "to": [ "research@dash.limited" ], "cc": [], "subject": "A quick question", "preview": "Could you help me find…", "labels": [ "unread" ], "in_reply_to": null, "created_at": "2026-10-05T09:01:00.000Z", "error": null } ], "next_cursor": null } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } } }, "/keys": { "get": { "tags": [ "API keys" ], "summary": "List API keys", "description": "List key metadata. Tokens and hashes are never returned. Account key required.", "operationId": "get__keys", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "data": [ { "id": "key_123", "name": "Research agent", "prefix": "dm_live_5e7f", "inbox_id": "inb_a1b2c3", "created_at": "2026-10-05T09:00:00.000Z" } ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } }, "post": { "tags": [ "API keys" ], "summary": "Create an API key", "description": "Tokens are shown once. Pass inbox_id to restrict the key to one inbox. Omit it to create an account key. Account key required.", "operationId": "post__keys", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "key_123", "name": "Research agent", "inbox_id": "inb_a1b2c3", "token": "dm_live_", "prefix": "dm_live_5e7f", "created_at": "2026-10-05T09:00:00.000Z" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Key name, 1–100 bytes." }, "inbox_id": { "type": "string", "description": "Optional inbox scope. Omit for an account key." } } }, "example": { "name": "Research agent", "inbox_id": "inb_a1b2c3" } } } } } }, "/keys/{key_id}": { "delete": { "tags": [ "API keys" ], "summary": "Revoke an API key", "description": "Immediately revoke a key. Use another account key to revoke the currently authenticated key.", "operationId": "delete__keys__key_id_", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "key_123", "deleted": true } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "description": "List webhook endpoints visible to this key. Signing secrets are omitted.", "operationId": "get__webhooks", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "data": [ { "id": "wh_123", "url": "https://your-app.com/hooks/mail", "inbox_id": "inb_a1b2c3", "enabled": 1, "created_at": "2026-10-05T09:00:00.000Z" } ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create a webhook", "description": "Subscribe to message.received and message.sent events. Pass inbox_id for a specific inbox, or omit it for all inboxes when using an account key. The signing secret is returned only on creation.", "operationId": "post__webhooks", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "wh_123", "url": "https://your-app.com/hooks/mail", "inbox_id": "inb_a1b2c3", "secret": "whsec_", "enabled": true, "created_at": "2026-10-05T09:00:00.000Z" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Public HTTPS endpoint, port 443, without credentials." }, "inbox_id": { "type": "string", "description": "Inbox to subscribe to. Omit for all inboxes; an inbox key defaults to its assigned inbox." } } }, "example": { "url": "https://your-app.com/hooks/mail", "inbox_id": "inb_a1b2c3" } } } } } }, "/webhooks/{webhook_id}": { "delete": { "tags": [ "Webhooks" ], "summary": "Disable a webhook", "description": "Stop future deliveries to this endpoint. Delivery history is retained.", "operationId": "delete__webhooks__webhook_id_", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "id": "wh_123", "enabled": false } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } } }, "/webhooks/{webhook_id}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook deliveries", "description": "Inspect the latest 100 deliveries, attempt counts and HTTP response codes. Up to six delivery attempts. A zero last_status indicates a network error.", "operationId": "get__webhooks__webhook_id__deliveries", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "data": [ { "id": "del_123", "event_id": "evt_123", "status": "delivered", "attempts": 1, "last_status": 200, "last_attempt_at": "2026-10-05T09:00:00.000Z" } ] } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Resource not found" }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } } } } }