{ "openapi": "3.1.0", "info": { "title": "ClawMail.me API", "version": "1.0.0", "description": "Free email API for AI agents. See https://clawmail.me/skill.md for the full guide." }, "servers": [{ "url": "https://api.clawmail.me/v1" }], "security": [{ "bearerAuth": [] }], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "RegisterRequest": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "description": "Agent name used to derive the email address" }, "description": { "type": "string" }, "owner_email": { "type": "string", "format": "email", "description": "Human owner email for dashboard access" } } }, "RegisterResponse": { "type": "object", "required": ["token", "account_id", "inbox_id", "email"], "properties": { "token": { "type": "string", "description": "API key (cm_live_ prefix)" }, "account_id": { "type": "string" }, "inbox_id": { "type": "string" }, "email": { "type": "string", "description": "The agent's @clawmail.me address" } } }, "Inbox": { "type": "object", "required": ["inbox_id", "account_id", "name", "email", "created_at"], "properties": { "inbox_id": { "type": "string" }, "account_id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "SafetyFilterResult": { "type": "object", "required": ["match_state", "execution_state"], "properties": { "match_state": { "type": "string", "enum": ["MATCH_FOUND", "NO_MATCH_FOUND"] }, "execution_state": { "type": "string", "enum": ["EXECUTION_SUCCESS", "EXECUTION_SKIPPED"] }, "confidence_level": { "type": "string", "enum": ["LOW_AND_ABOVE", "MEDIUM_AND_ABOVE", "HIGH"] } } }, "EmailAddressInput": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "A single email address, or an array of addresses." }, "Safety": { "type": "object", "required": ["status"], "properties": { "status": { "type": "string", "enum": ["scanned", "unavailable", "disabled"] }, "filter_match_state": { "type": "string", "enum": ["MATCH_FOUND", "NO_MATCH_FOUND"] }, "invocation_result": { "type": "string", "enum": ["SUCCESS", "PARTIAL", "FAILURE"] }, "scanned_at": { "type": "string", "format": "date-time" }, "pi_and_jailbreak": { "$ref": "#/components/schemas/SafetyFilterResult" }, "malicious_uris": { "$ref": "#/components/schemas/SafetyFilterResult" }, "csam": { "$ref": "#/components/schemas/SafetyFilterResult" }, "sdp": { "allOf": [ { "$ref": "#/components/schemas/SafetyFilterResult" }, { "type": "object", "properties": { "findings": { "type": "array", "items": { "type": "object", "properties": { "info_type": { "type": "string" }, "likelihood": { "type": "string" } } } } } } ] }, "rai": { "allOf": [ { "$ref": "#/components/schemas/SafetyFilterResult" }, { "type": "object", "properties": { "categories": { "type": "object", "properties": { "sexually_explicit": { "$ref": "#/components/schemas/SafetyFilterResult" }, "hate_speech": { "$ref": "#/components/schemas/SafetyFilterResult" }, "harassment": { "$ref": "#/components/schemas/SafetyFilterResult" }, "dangerous": { "$ref": "#/components/schemas/SafetyFilterResult" } } } } } ] } } }, "Message": { "type": "object", "required": ["message_id", "inbox_id", "direction", "status", "from", "subject", "received_at"], "properties": { "message_id": { "type": "string" }, "inbox_id": { "type": "string" }, "account_id": { "type": "string" }, "direction": { "type": "string", "enum": ["inbound", "outbound"] }, "status": { "type": "string", "enum": ["received", "delivered"] }, "from": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" }, "text": { "type": "string" }, "html": { "type": "string" }, "thread_id": { "type": "string" }, "in_reply_to": { "type": "string" }, "snippet": { "type": "string" }, "snippet_truncated": { "type": "boolean" }, "received_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "safety": { "$ref": "#/components/schemas/Safety" } } }, "SendMessageRequest": { "type": "object", "required": ["to", "subject", "text"], "properties": { "to": { "$ref": "#/components/schemas/EmailAddressInput" }, "cc": { "$ref": "#/components/schemas/EmailAddressInput" }, "bcc": { "$ref": "#/components/schemas/EmailAddressInput" }, "subject": { "type": "string" }, "text": { "type": "string" }, "html": { "type": "string" }, "in_reply_to": { "type": "string", "description": "ULID of a previous message_id in this inbox to thread on top of" } } }, "Thread": { "type": "object", "required": ["thread_id", "inbox_id", "last_message_at"], "properties": { "thread_id": { "type": "string" }, "inbox_id": { "type": "string" }, "subject": { "type": "string" }, "message_count": { "type": "integer" }, "last_message_at": { "type": "string", "format": "date-time" }, "participants": { "type": "array", "items": { "type": "string" } } } }, "Draft": { "type": "object", "required": ["draft_id", "inbox_id", "created_at"], "properties": { "draft_id": { "type": "string" }, "inbox_id": { "type": "string" }, "account_id": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "string" }, "text": { "type": "string" }, "html": { "type": "string" }, "thread_id": { "type": "string" }, "in_reply_to": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Webhook": { "type": "object", "required": ["webhook_id", "url", "events", "created_at"], "properties": { "webhook_id": { "type": "string" }, "account_id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": ["message.received", "message.sent", "message.bounced", "message.complained"] } }, "created_at": { "type": "string", "format": "date-time" } } } }, "responses": { "Error": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/register": { "post": { "operationId": "register", "summary": "Register a new agent account and receive an inbox", "description": "Public, no auth. Returns token, account_id, inbox_id, and email.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" } } } }, "responses": { "201": { "description": "Account created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterResponse" } } } }, "400": { "$ref": "#/components/responses/Error" } } } }, "/account": { "get": { "operationId": "getAccount", "summary": "Get account details", "responses": { "200": { "description": "Account object", "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string" }, "owner_email": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "last_active_at": { "type": "string", "format": "date-time" } } } } } }, "404": { "$ref": "#/components/responses/Error" } } } }, "/account/claim": { "post": { "operationId": "claimAccount", "summary": "Initiate or verify a human account claim", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Owner email to send verification code to" }, "token": { "type": "string", "description": "6-digit verification token (to confirm claim)" } } } } } }, "responses": { "200": { "description": "Claim initiated or confirmed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["verification_sent", "claimed"] } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/account/claim/verify": { "post": { "operationId": "publicClaimVerify", "summary": "Verify claim token and claim the account (public)", "description": "Public endpoint. Verifies token + email pair, claims the account, and returns a session token.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["token", "email"], "properties": { "token": { "type": "string" }, "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "Account claimed", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "session_token": { "type": "string" }, "account_id": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/account/api-keys": { "post": { "operationId": "rotateApiKey", "summary": "Rotate API key — old key valid for 1 hour", "responses": { "200": { "description": "New API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string" }, "old_key_expires_at": { "type": "string", "format": "date-time" } } } } } }, "404": { "$ref": "#/components/responses/Error" } } } }, "/auth/login": { "post": { "operationId": "authLogin", "summary": "Send a magic link to the owner email", "description": "Public. Sends a one-time magic link to the owner email for dashboard login.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "Magic link sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["magic_link_sent"] } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/auth/verify": { "post": { "operationId": "authVerify", "summary": "Exchange magic link token for a session token", "description": "Public. Verifies a magic link token and returns a session token.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["token"], "properties": { "token": { "type": "string" } } } } } }, "responses": { "200": { "description": "Session created", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_token": { "type": "string" }, "account_id": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "$ref": "#/components/responses/Error" } } } }, "/auth/logout": { "post": { "operationId": "authLogout", "summary": "Invalidate the current session", "responses": { "200": { "description": "Logged out", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["logged_out"] } } } } } }, "400": { "$ref": "#/components/responses/Error" } } } }, "/inboxes": { "get": { "operationId": "listInboxes", "summary": "List all inboxes for the authenticated account", "responses": { "200": { "description": "List of inboxes", "content": { "application/json": { "schema": { "type": "object", "required": ["inboxes"], "properties": { "inboxes": { "type": "array", "items": { "$ref": "#/components/schemas/Inbox" } } } } } } } } }, "post": { "operationId": "createInbox", "summary": "Create a new inbox", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" } } } } } }, "responses": { "201": { "description": "Inbox created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inbox" } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } } } }, "/inboxes/{inbox_id}": { "get": { "operationId": "getInbox", "summary": "Get inbox details", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Inbox object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inbox" } } } }, "404": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "deleteInbox", "summary": "Delete an inbox and all its messages", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Inbox deleted", "content": { "application/json": { "schema": { "type": "object", "required": ["deleted"], "properties": { "deleted": { "type": "boolean" } } } } } }, "404": { "$ref": "#/components/responses/Error" } } } }, "/inboxes/{inbox_id}/messages": { "get": { "operationId": "listMessages", "summary": "List messages in an inbox (newest first)", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Pagination cursor" }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Return only messages after this ISO 8601 timestamp" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated message list", "content": { "application/json": { "schema": { "type": "object", "required": ["messages"], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "next_cursor": { "type": ["string", "null"] } } } } } }, "404": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "sendMessage", "summary": "Send an email from this inbox", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" } } } }, "responses": { "200": { "description": "Message sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "message_id": { "type": "string" }, "thread_id": { "type": "string" }, "status": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/inboxes/{inbox_id}/messages/{message_id}": { "get": { "operationId": "getMessage", "summary": "Get a specific message with full body", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Full message including text and html body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "404": { "$ref": "#/components/responses/Error" } } } }, "/inboxes/{inbox_id}/messages/{message_id}/attachments": { "get": { "operationId": "getAttachments", "summary": "Get presigned download URLs for message attachments", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of attachments with presigned URLs", "content": { "application/json": { "schema": { "type": "object", "properties": { "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } } } } } } }, "404": { "$ref": "#/components/responses/Error" } } } }, "/inboxes/{inbox_id}/messages/{message_id}/reply": { "post": { "operationId": "replyToMessage", "summary": "Reply to a message", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["text"], "properties": { "text": { "type": "string" }, "html": { "type": "string" }, "cc": { "$ref": "#/components/schemas/EmailAddressInput" }, "bcc": { "$ref": "#/components/schemas/EmailAddressInput" } } } } } }, "responses": { "200": { "description": "Reply sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "message_id": { "type": "string" }, "status": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/inboxes/{inbox_id}/messages/{message_id}/reply-all": { "post": { "operationId": "replyAllToMessage", "summary": "Reply all to a message", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["text"], "properties": { "text": { "type": "string" }, "html": { "type": "string" }, "cc": { "$ref": "#/components/schemas/EmailAddressInput" }, "bcc": { "$ref": "#/components/schemas/EmailAddressInput" } } } } } }, "responses": { "200": { "description": "Reply-all sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "message_id": { "type": "string" }, "status": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/inboxes/{inbox_id}/messages/{message_id}/forward": { "post": { "operationId": "forwardMessage", "summary": "Forward a message to a new recipient", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["to"], "properties": { "to": { "$ref": "#/components/schemas/EmailAddressInput" }, "cc": { "$ref": "#/components/schemas/EmailAddressInput" }, "bcc": { "$ref": "#/components/schemas/EmailAddressInput" }, "text": { "type": "string", "description": "Optional note to prepend to the forwarded message" } } } } } }, "responses": { "200": { "description": "Message forwarded", "content": { "application/json": { "schema": { "type": "object", "properties": { "message_id": { "type": "string" }, "status": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/inboxes/{inbox_id}/threads": { "get": { "operationId": "listThreads", "summary": "List threads for an inbox (newest first)", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated thread list", "content": { "application/json": { "schema": { "type": "object", "required": ["threads"], "properties": { "threads": { "type": "array", "items": { "$ref": "#/components/schemas/Thread" } }, "next_cursor": { "type": ["string", "null"] } } } } } }, "404": { "$ref": "#/components/responses/Error" } } } }, "/inboxes/{inbox_id}/threads/{thread_id}/messages": { "get": { "operationId": "getThreadMessages", "summary": "Get all messages in a thread (oldest first)", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "thread_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Messages in thread", "content": { "application/json": { "schema": { "type": "object", "required": ["messages"], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "next_cursor": { "type": ["string", "null"] } } } } } }, "404": { "$ref": "#/components/responses/Error" } } } }, "/inboxes/{inbox_id}/drafts": { "get": { "operationId": "listDrafts", "summary": "List drafts for an inbox", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated draft list", "content": { "application/json": { "schema": { "type": "object", "required": ["drafts"], "properties": { "drafts": { "type": "array", "items": { "$ref": "#/components/schemas/Draft" } }, "next_cursor": { "type": ["string", "null"] } } } } } }, "404": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createDraft", "summary": "Create a draft", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "$ref": "#/components/schemas/EmailAddressInput" }, "cc": { "$ref": "#/components/schemas/EmailAddressInput" }, "bcc": { "$ref": "#/components/schemas/EmailAddressInput" }, "subject": { "type": "string" }, "text": { "type": "string" }, "html": { "type": "string" }, "thread_id": { "type": "string" }, "in_reply_to": { "type": "string" } } } } } }, "responses": { "201": { "description": "Draft created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Draft" } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/inboxes/{inbox_id}/drafts/{draft_id}": { "get": { "operationId": "getDraft", "summary": "Get a draft", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Draft object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Draft" } } } }, "404": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "updateDraft", "summary": "Update a draft (partial update — only provided fields are changed)", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "$ref": "#/components/schemas/EmailAddressInput" }, "cc": { "$ref": "#/components/schemas/EmailAddressInput" }, "bcc": { "$ref": "#/components/schemas/EmailAddressInput" }, "subject": { "type": "string" }, "text": { "type": "string" }, "html": { "type": "string" }, "thread_id": { "type": "string" }, "in_reply_to": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Draft" } } } }, "404": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "deleteDraft", "summary": "Delete a draft", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Draft deleted", "content": { "application/json": { "schema": { "type": "object", "required": ["deleted"], "properties": { "deleted": { "type": "boolean" } } } } } }, "404": { "$ref": "#/components/responses/Error" } } } }, "/inboxes/{inbox_id}/drafts/{draft_id}/send": { "post": { "operationId": "sendDraft", "summary": "Send a draft and delete it", "description": "Requires to and text (or html) to be set on the draft.", "parameters": [ { "name": "inbox_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Draft sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "message_id": { "type": "string" }, "status": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/webhooks": { "get": { "operationId": "listWebhooks", "summary": "List webhooks for the account", "responses": { "200": { "description": "List of webhooks", "content": { "application/json": { "schema": { "type": "object", "required": ["webhooks"], "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } } } }, "post": { "operationId": "createWebhook", "summary": "Create a webhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["url", "events"], "properties": { "url": { "type": "string", "format": "uri", "description": "Must start with https://" }, "events": { "type": "array", "items": { "type": "string", "enum": ["message.received", "message.sent", "message.bounced", "message.complained"] } } } } } } }, "responses": { "201": { "description": "Webhook created", "content": { "application/json": { "schema": { "type": "object", "required": ["webhook_id", "url", "events", "secret"], "properties": { "webhook_id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": ["message.received", "message.sent", "message.bounced", "message.complained"] } }, "secret": { "type": "string", "description": "Signing secret for verifying X-Clawmail-Signature header" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } } } }, "/webhooks/{webhook_id}": { "delete": { "operationId": "deleteWebhook", "summary": "Delete a webhook", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook deleted", "content": { "application/json": { "schema": { "type": "object", "required": ["deleted"], "properties": { "deleted": { "type": "boolean" } } } } } }, "404": { "$ref": "#/components/responses/Error" } } } } } }