{"openapi":"3.1.0","info":{"title":"Super Mail Hub API","version":"1.0.0","description":"Send transactional email, read message delivery status, and consume signed delivery webhooks."},"servers":[{"url":"https://your-domain.example","description":"Your Super Mail Hub origin"}],"tags":[{"name":"Messages","description":"Transactional sending and delivery status."}],"paths":{"/api/v1/send":{"post":{"tags":["Messages"],"summary":"Queue a transactional email","operationId":"sendMessage","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageRequest"}}}},"responses":{"202":{"description":"Message accepted for asynchronous delivery.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The workspace plan does not include active API sending.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks mail.send or the workspace is blocked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The recipient is suppressed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A rolling-hour, daily, or monthly sending limit was reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/messages/{messageId}":{"get":{"tags":["Messages"],"summary":"Get processing and delivery status","operationId":"getMessageStatus","security":[{"bearerAuth":[]}],"parameters":[{"name":"messageId","in":"path","required":true,"description":"The UUID returned by the send endpoint.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current message and provider-reported delivery events.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDeliveryStatus"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The key lacks mail.status.read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No outbound message with that ID exists in the authenticated workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"messageStatusChanged":{"post":{"summary":"Signed message lifecycle event","description":"Configured in Workspace → API & SMTP. Verify Webhook-Signature against the unmodified request body and return a 2xx response promptly.","parameters":[{"name":"Webhook-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Webhook-Timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"Webhook-Signature","in":"header","required":true,"schema":{"type":"string","example":"v1=9f…"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Event acknowledged."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Super Mail Hub API key","description":"Create a scoped key in Workspace → API & SMTP."}},"responses":{"BadRequest":{"description":"Malformed or invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string"},"upgradeUrl":{"type":"string"}}},"Attachment":{"type":"object","required":["filename","contentBase64"],"properties":{"filename":{"type":"string"},"contentType":{"type":"string","default":"application/octet-stream"},"contentBase64":{"type":"string","format":"byte"}}},"SendMessageRequest":{"type":"object","required":["mailboxId","recipient","subject","bodyText"],"properties":{"mailboxId":{"type":"string","format":"uuid","description":"An active mailbox owned by the authenticated workspace."},"recipient":{"type":"string","format":"email"},"subject":{"type":"string"},"bodyText":{"type":"string"},"attachments":{"type":"array","maxItems":10,"description":"Maximum 20 MB decoded total; every file is malware-scanned.","items":{"$ref":"#/components/schemas/Attachment"}}}},"Message":{"type":"object","required":["id","mailboxId","direction","status","sender","recipient","subject","bodyText","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"mailboxId":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["outbound"]},"status":{"type":"string","enum":["queued","sending","sent","retrying","failed","delivery_unknown"]},"sender":{"type":"string","format":"email"},"recipient":{"type":"string","format":"email"},"subject":{"type":"string"},"bodyText":{"type":"string"},"providerMessageId":{"type":"string"},"errorMessage":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"SendMessageResponse":{"type":"object","required":["id","status","message"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","example":"queued"},"message":{"$ref":"#/components/schemas/Message"}}},"DeliveryEvent":{"type":"object","required":["id","eventType","recipient","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"eventType":{"type":"string","enum":["delivered","soft_bounce","hard_bounce","complaint"]},"recipient":{"type":"string","format":"email"},"detail":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"MessageDeliveryStatus":{"type":"object","required":["message","processingStatus","deliveryStatus","events"],"properties":{"message":{"$ref":"#/components/schemas/Message"},"processingStatus":{"type":"string"},"deliveryStatus":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryEvent"}}}},"WebhookEvent":{"type":"object","required":["id","type","createdAt","apiVersion","data"],"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["webhook.test","message.queued","message.sending","message.sent","message.retrying","message.delivered","message.soft_bounced","message.hard_bounced","message.complained","message.failed","message.delivery_unknown"]},"createdAt":{"type":"string","format":"date-time"},"apiVersion":{"type":"string","example":"2026-08-18"},"data":{"type":"object","additionalProperties":true}}}}}}