{"openapi":"3.1.0","info":{"title":"Sendas API","version":"1.0.0","description":"Manage domains, addresses and SMTP passwords for Sendas. Create an API key in the dashboard and send it as `Authorization: Bearer sk_...`."},"servers":[{"url":"/api/v1"}],"security":[{"apiKey":[]}],"paths":{"/me":{"get":{"summary":"Current account and plan limits","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Account"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/domains":{"get":{"summary":"List domains","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Domain"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Add a domain","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"yourcompany.com"}},"required":["name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Domain"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/domains/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a domain with the DNS records to publish","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Domain"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Remove a domain and all its addresses","responses":{"204":{"description":"Deleted"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/domains/{id}/verify":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Check DNS records; the domain goes live once all required records are found","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Verification"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/domains/{id}/aliases":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"List addresses","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Alias"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Create an address; mail is forwarded to your Gmail","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"localPart":{"type":"string","example":"hr"}},"required":["localPart"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Alias"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/domains/{id}/logs":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"before","in":"query","schema":{"type":"string"},"description":"Cursor from nextBefore"}],"get":{"summary":"Message log for the last 7 days (metadata only, never message bodies)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LogPage"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/aliases/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"summary":"Pause or resume an address","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"active":{"type":"boolean"}},"required":["active"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Alias"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Delete an address","responses":{"204":{"description":"Deleted"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/aliases/{id}/smtp-credentials":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"List live SMTP passwords (the passwords themselves are never shown again)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Credential"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Create an SMTP password for Gmail \"Send mail as\". Returned once.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","example":"Gmail"}},"required":[]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NewCredential"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/aliases/{id}/forwards":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Teammates who also receive this address’s mail","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Forward"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Invite a teammate. They get a confirmation email; nothing is forwarded until they confirm. Up to 5 per address.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","example":"teammate@gmail.com"}},"required":["email"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Forward"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/forwards/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"summary":"Stop forwarding to a teammate","responses":{"204":{"description":"Removed"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/smtp-credentials/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"summary":"Revoke an SMTP password","responses":{"204":{"description":"Revoked"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/webhooks":{"get":{"summary":"List webhooks with their last delivery result","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Add an HTTPS endpoint for message events (up to 3). Leave out events to get all of them. The signing secret is returned once.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","example":"https://example.com/hooks/sendas"},"events":{"type":"array","items":{"$ref":"#/components/schemas/EventType"},"example":["message.received","message.bounced"]}},"required":["url"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NewWebhook"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/webhooks/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"summary":"Change the URL or events, or switch a webhook off and on. Switching on resets its failure count.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/EventType"}},"active":{"type":"boolean"}},"required":[]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Webhook"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Delete a webhook","responses":{"204":{"description":"Deleted"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/webhooks/{id}/test":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Send a webhook.test event to the endpoint within a few seconds","responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"eventId":{"type":"string"}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}}},"webhooks":{"message.received":{"post":{"summary":"Mail to one of your addresses was forwarded","parameters":[{"name":"Sendas-Signature","in":"header","required":true,"schema":{"type":"string","example":"t=1762160000,v1=5257a8..."}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Any 2xx status counts as delivered. Anything else, or no answer within 10 s, is retried."}}}},"message.sent":{"post":{"summary":"Mail was sent from Gmail through Sendas","parameters":[{"name":"Sendas-Signature","in":"header","required":true,"schema":{"type":"string","example":"t=1762160000,v1=5257a8..."}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Any 2xx status counts as delivered. Anything else, or no answer within 10 s, is retried."}}}},"message.bounced":{"post":{"summary":"A receiving server refused mail after it left Sendas (forwarded or sent)","parameters":[{"name":"Sendas-Signature","in":"header","required":true,"schema":{"type":"string","example":"t=1762160000,v1=5257a8..."}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Any 2xx status counts as delivered. Anything else, or no answer within 10 s, is retried."}}}},"message.rejected":{"post":{"summary":"Incoming mail was refused, for example for failing DMARC","parameters":[{"name":"Sendas-Signature","in":"header","required":true,"schema":{"type":"string","example":"t=1762160000,v1=5257a8..."}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Any 2xx status counts as delivered. Anything else, or no answer within 10 s, is retried."}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key from the dashboard (sk_...)"}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}},"schemas":{"Account":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"name":{"type":["string","null"]},"plan":{"type":"string"},"limits":{"type":"object"},"smtp":{"type":"object","properties":{"host":{"type":"string"},"port":{"type":"integer"},"security":{"type":"string"}}}}},"DnsRecord":{"type":"object","properties":{"kind":{"enum":["ownership","mx","spf","dkim","dmarc"]},"type":{"enum":["TXT","MX","CNAME"]},"host":{"type":"string","description":"Fully qualified name"},"name":{"type":"string","description":"Name as most DNS panels expect it: \"@\" or the part before the domain"},"value":{"type":"string"},"priority":{"type":"integer"},"required":{"type":"boolean"}}},"Domain":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"verified":{"type":"boolean"},"verifiedAt":{"type":["string","null"],"format":"date-time"},"dailySendLimit":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"dnsRecords":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecord"}}}},"Verification":{"type":"object","properties":{"verified":{"type":"boolean"},"records":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/DnsRecord"},{"type":"object","properties":{"ok":{"type":"boolean"},"hint":{"type":"string","description":"How to fix the record, when we can tell"}}}]}},"provider":{"type":["object","null"],"properties":{"name":{"type":"string"},"url":{"type":"string"},"tip":{"type":"string"}},"description":"DNS provider detected from nameservers"}}},"Alias":{"type":"object","properties":{"id":{"type":"string"},"domainId":{"type":"string"},"localPart":{"type":"string"},"destination":{"type":"string"},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"Forward":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"status":{"enum":["pending","active"]},"createdAt":{"type":"string"}}},"Credential":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":["string","null"]},"lastUsedAt":{"type":["string","null"]},"createdAt":{"type":"string"}}},"NewCredential":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":["string","null"]},"createdAt":{"type":"string"},"smtp":{"type":"object","properties":{"host":{"type":"string"},"port":{"type":"integer"},"security":{"type":"string"},"username":{"type":"string"},"password":{"type":"string"}}}}},"EventType":{"enum":["message.received","message.sent","message.bounced","message.rejected"]},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/EventType"}},"active":{"type":"boolean","description":"Switched off after 50 failed attempts in a row"},"lastAttemptAt":{"type":["string","null"]},"lastStatus":{"type":["integer","null"],"description":"HTTP status of the last attempt"},"lastError":{"type":["string","null"]},"consecutiveFailures":{"type":"integer"},"createdAt":{"type":"string"}}},"NewWebhook":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","properties":{"secret":{"type":"string","description":"whsec_... Shown once."}}}]},"Event":{"type":"object","properties":{"id":{"type":"string","description":"Same as the Sendas-Event-Id header. Retries keep the id, so use it to skip duplicates."},"type":{"type":"string","example":"message.received"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","description":"Metadata only. Message bodies are never sent.","properties":{"id":{"type":"string","description":"Message log entry id"},"domain":{"type":"string"},"address":{"type":["string","null"]},"direction":{"enum":["inbound","outbound"]},"status":{"enum":["forwarded","sent","rejected","bounced"]},"from":{"type":"string"},"to":{"type":"string"},"subject":{"type":["string","null"]},"messageId":{"type":["string","null"]},"reason":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}}}},"LogPage":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"direction":{"enum":["inbound","outbound"]},"status":{"enum":["forwarded","sent","rejected","bounced"]},"mailFrom":{"type":"string"},"rcptTo":{"type":"string"},"subject":{"type":["string","null"]},"reason":{"type":["string","null"]},"createdAt":{"type":"string"}}}},"nextBefore":{"type":["string","null"]}}}}}}