{"openapi":"3.1.0","info":{"title":"SentFromAI API","version":"0.1.0","description":"Comms infrastructure for AI agents. Email send/receive, threading, attachments, drafts, webhooks, realtime, and search."},"servers":[{"url":"https://api.sentfrom.ai/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"inboxes"},{"name":"messages"},{"name":"threads"},{"name":"drafts"},{"name":"webhooks"},{"name":"labels"},{"name":"lists"},{"name":"attachments"},{"name":"domains","description":"Custom sending domains"}],"paths":{"/inboxes":{"post":{"tags":["inboxes"],"operationId":"createInbox","summary":"Create an inbox","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInbox"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Inbox"}}}}}},"get":{"tags":["inboxes"],"operationId":"listInboxes","summary":"List inboxes","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"inboxes":{"type":"array","items":{"$ref":"#/components/schemas/Inbox"}}}}}}}}}},"/inboxes/{id}":{"delete":{"tags":["inboxes"],"operationId":"deleteInbox","summary":"Delete an inbox","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"204":{"description":"Deleted"}}}},"/messages":{"post":{"tags":["messages"],"operationId":"sendMessage","summary":"Send a message","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessage"}}}},"responses":{"201":{"description":"Sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendResult"}}}},"422":{"description":"All recipients suppressed or blocked"}}},"get":{"tags":["messages"],"operationId":"searchMessages","summary":"Search messages","parameters":[{"name":"query","in":"query","schema":{"type":"string"}},{"name":"mode","in":"query","schema":{"type":"string","enum":["keyword","semantic","hybrid"]}},{"name":"inbox_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"mode_used":{"type":"string"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}}}}}}}}}},"/messages/{id}":{"get":{"tags":["messages"],"operationId":"getMessage","summary":"Get a message","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"404":{"description":"Not found"}}}},"/messages/{id}/reply":{"post":{"tags":["messages"],"operationId":"replyToMessage","summary":"Reply in thread","parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"html":{"type":"string"},"reply_all":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendResult"}}}}}}},"/messages/{id}/forward":{"post":{"tags":["messages"],"operationId":"forwardMessage","summary":"Forward a message","parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to"],"properties":{"to":{"type":"array","items":{"type":"string"}},"text":{"type":"string"},"from_inbox_id":{"type":"string"}}}}}},"responses":{"201":{"description":"Sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendResult"}}}}}}},"/threads":{"get":{"tags":["threads"],"operationId":"listThreads","summary":"List threads","parameters":[{"name":"inbox_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"threads":{"type":"array","items":{"$ref":"#/components/schemas/Thread"}}}}}}}}}},"/threads/{id}":{"get":{"tags":["threads"],"operationId":"getThread","summary":"Get a thread with messages","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Thread"}}}}}}},"/drafts":{"post":{"tags":["drafts"],"operationId":"createDraft","summary":"Create a draft","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDraft"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Draft"}}}}}},"get":{"tags":["drafts"],"operationId":"listDrafts","summary":"List drafts","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"drafts":{"type":"array","items":{"$ref":"#/components/schemas/Draft"}}}}}}}}}},"/drafts/{id}":{"get":{"tags":["drafts"],"operationId":"getDraft","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Draft"}}}}}},"patch":{"tags":["drafts"],"operationId":"updateDraft","parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDraft"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Draft"}}}}}},"delete":{"tags":["drafts"],"operationId":"deleteDraft","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"204":{"description":"Deleted"}}}},"/drafts/{id}/send":{"post":{"tags":["drafts"],"operationId":"sendDraft","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"201":{"description":"Sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendResult"}}}}}}},"/webhooks":{"post":{"tags":["webhooks"],"operationId":"createWebhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Created"}}},"get":{"tags":["webhooks"],"operationId":"listWebhooks","responses":{"200":{"description":"OK"}}}},"/webhooks/{id}":{"delete":{"tags":["webhooks"],"operationId":"deleteWebhook","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"204":{"description":"Deleted"}}}},"/labels":{"post":{"tags":["labels"],"operationId":"createLabel","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"color":{"type":"string"}}}}}},"responses":{"201":{"description":"Created"}}},"get":{"tags":["labels"],"operationId":"listLabels","responses":{"200":{"description":"OK"}}}},"/labels/{id}":{"delete":{"tags":["labels"],"operationId":"deleteLabel","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"204":{"description":"Deleted"}}}},"/labels/{id}/assign":{"post":{"tags":["labels"],"operationId":"assignLabel","parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message_id"],"properties":{"message_id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"}}}},"/labels/{id}/unassign":{"post":{"tags":["labels"],"operationId":"unassignLabel","parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message_id"],"properties":{"message_id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"}}}},"/lists":{"post":{"tags":["lists"],"operationId":"createRule","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","pattern"],"properties":{"kind":{"type":"string","enum":["allow","block"]},"direction":{"type":"string","enum":["inbound","outbound","both"]},"pattern":{"type":"string"}}}}}},"responses":{"201":{"description":"Created"}}},"get":{"tags":["lists"],"operationId":"listRules","responses":{"200":{"description":"OK"}}}},"/lists/{id}":{"delete":{"tags":["lists"],"operationId":"deleteRule","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"204":{"description":"Deleted"}}}},"/attachments/{id}":{"get":{"tags":["attachments"],"operationId":"getAttachment","summary":"Get a signed download URL","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Attachment"}}}}}}},"/domains":{"post":{"tags":["domains"],"operationId":"createDomain","summary":"Add a custom domain","description":"Add a bring-your-own domain. Returns the DNS records to publish. Requires a paid plan.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDomain"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainWithRecords"}}}},"402":{"description":"Plan upgrade required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"upgrade":{"type":"boolean"}}}}}}}},"get":{"tags":["domains"],"operationId":"listDomains","summary":"List domains","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"type":"array","items":{"$ref":"#/components/schemas/Domain"}}}}}}}}}},"/domains/subdomain":{"post":{"tags":["domains"],"operationId":"createSubdomain","summary":"Provision a dedicated subdomain","description":"Provision <label>.sentfrom.ai with DNS auto-configured for isolated sending reputation. Requires Scale or higher.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubdomain"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainWithRecords"}}}},"402":{"description":"Plan upgrade required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"upgrade":{"type":"boolean"}}}}}}}}},"/domains/{id}":{"get":{"tags":["domains"],"operationId":"getDomain","summary":"Get a domain","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainWithRecords"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}},"delete":{"tags":["domains"],"operationId":"deleteDomain","summary":"Delete a domain","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/domains/{id}/dmarc":{"post":{"tags":["domains"],"operationId":"setDmarcPolicy","summary":"Set DMARC policy","description":"Ramp the DMARC policy (none -> quarantine -> reject).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetDmarc"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"hostname":{"type":"string"},"dmarc_policy":{"type":"string"},"record":{"$ref":"#/components/schemas/DnsRecord"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/domains/{id}/verify":{"post":{"tags":["domains"],"operationId":"verifyDomain","summary":"Re-check verification","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"hostname":{"type":"string"},"status":{"type":"string"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"parameters":{"Id":{"name":"id","in":"path","required":true,"schema":{"type":"string"}}},"schemas":{"CreateInbox":{"type":"object","required":["local_part"],"properties":{"local_part":{"type":"string"},"display_name":{"type":"string"},"domain_id":{"type":"string"}}},"Inbox":{"type":"object","properties":{"id":{"type":"string"},"local_part":{"type":"string"},"display_name":{"type":["string","null"]},"address":{"type":"string"}}},"Attachment":{"type":"object","properties":{"filename":{"type":["string","null"]},"content_type":{"type":"string"},"content_base64":{"type":"string"}}},"SendMessage":{"type":"object","required":["inbox_id","to","subject"],"properties":{"inbox_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"},"in_reply_to":{"type":"string"},"references":{"type":"array","items":{"type":"string"}},"client_id":{"type":"string"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}}}},"SendResult":{"type":"object","properties":{"id":{"type":"string"},"thread_id":{"type":"string"},"message_id":{"type":"string"},"ses_message_id":{"type":"string"},"idempotent":{"type":"boolean"}}},"Message":{"type":"object","properties":{"id":{"type":"string"},"thread_id":{"type":"string"},"direction":{"type":"string"},"from_addr":{"type":"string"},"to_addrs":{"type":"array","items":{"type":"string"}},"subject":{"type":["string","null"]},"body_text":{"type":["string","null"]},"delivery_status":{"type":"string"}}},"Thread":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":["string","null"]},"last_message_at":{"type":"string"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}}}},"CreateDraft":{"type":"object","required":["inbox_id"],"properties":{"inbox_id":{"type":"string"},"to":{"type":"array","items":{"type":"string"}},"subject":{"type":"string"},"text":{"type":"string"},"html":{"type":"string"},"reply_to_message_id":{"type":"string"},"scheduled_at":{"type":"string"}}},"Draft":{"type":"object","properties":{"id":{"type":"string"},"inbox_id":{"type":"string"},"subject":{"type":["string","null"]},"status":{"type":"string"},"scheduled_at":{"type":["string","null"]}}},"DnsRecord":{"type":"object","properties":{"type":{"type":"string","enum":["CNAME","TXT","MX"]},"name":{"type":"string","description":"Fully-qualified record name"},"content":{"type":"string"},"priority":{"type":"integer","nullable":true,"description":"For MX records"},"purpose":{"type":"string","description":"dkim | spf | dmarc | inbound-mx | mailfrom-mx | mailfrom-spf"}},"required":["type","name","content","purpose"]},"Domain":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"hostname":{"type":"string","example":"mail.yourcompany.com"},"kind":{"type":"string","enum":["system","tenant_subdomain","byo"]},"status":{"type":"string","enum":["pending","verifying","verified","failed"]},"mail_from_domain":{"type":"string","nullable":true},"mail_from_status":{"type":"string","enum":["pending","success","failed"],"nullable":true},"dmarc_policy":{"type":"string","enum":["none","quarantine","reject"]},"verified_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"DomainWithRecords":{"allOf":[{"$ref":"#/components/schemas/Domain"},{"type":"object","properties":{"records":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecord"}}}}]},"CreateDomain":{"type":"object","required":["hostname"],"properties":{"hostname":{"type":"string","example":"mail.yourcompany.com"}}},"CreateSubdomain":{"type":"object","required":["label"],"properties":{"label":{"type":"string","pattern":"^[a-z0-9-]+$","example":"acme"}}},"SetDmarc":{"type":"object","required":["policy"],"properties":{"policy":{"type":"string","enum":["none","quarantine","reject"]}}}}}}