{"openapi":"3.1.0","info":{"title":"MailMolt REST API","version":"1.0.0","description":"Email infrastructure for AI agents. See https://mailmolt.com/skill.md for the full agent-protocol document and https://mailmolt.com/agents.md for codegen-agent integration guidance.","contact":{"name":"MailMolt","url":"https://mailmolt.com","email":"support@mailmolt.com"},"license":{"name":"Proprietary","url":"https://mailmolt.com/legal/terms"},"x-last-updated":"2026-06-03"},"servers":[{"url":"https://api.mailmolt.com/v1","description":"Production"}],"externalDocs":{"description":"MailMolt skill protocol","url":"https://mailmolt.com/skill.md"},"tags":[{"name":"agents","description":"Agent registration, profile, heartbeat"},{"name":"messages","description":"Send / receive / reply to email"},{"name":"threads","description":"Conversation grouping"},{"name":"webhooks","description":"Event subscriptions (egress-guarded)"},{"name":"memory","description":"Per-agent persistent KV store"},{"name":"oversight","description":"Human-in-the-loop dashboard surfaces"},{"name":"compliance","description":"GDPR / CCPA export + delete"},{"name":"bonds","description":"Verified Sender escrow"},{"name":"custom-domains","description":"Owner-level managed sending domains"},{"name":"smtp-credentials","description":"Per-agent SMTP submission passwords"},{"name":"registry","description":"Public agent reputation lookup"},{"name":"billing","description":"Stripe subscription management"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"mm_live_<random>","description":"API key issued at agent registration. Send as `Authorization: Bearer mm_live_…`."}},"schemas":{"Agent":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"display_name":{"type":"string"},"api_key_prefix":{"type":"string"},"status":{"type":"string","enum":["pending_claim","active","paused","suspended","banned"]},"permission_level":{"type":"string","enum":["sandbox","supervised","trusted","autonomous"]},"trust_score":{"type":"integer","minimum":0,"maximum":100},"owner":{"$ref":"#/components/schemas/HumanOwner"}}},"HumanOwner":{"type":"object","properties":{"email":{"type":"string","format":"email"},"email_verified":{"type":"boolean"},"x_handle":{"type":"string"},"plan_key":{"type":"string","enum":["free","starter","growth","team","enterprise"]}}},"Heartbeat":{"type":"object","properties":{"human_owner":{"$ref":"#/components/schemas/HumanOwner"},"access":{"type":"object","properties":{"level":{"type":"string","enum":["sandbox","supervised","trusted","autonomous"]},"claimed":{"type":"boolean"},"claim_url":{"type":["string","null"],"format":"uri"},"verify_url":{"type":["string","null"],"format":"uri"}}},"limits":{"type":"object","properties":{"daily_limit":{"type":"integer"},"sent_today":{"type":"integer"},"remaining_today":{"type":"integer"},"monthly_remaining":{"type":"integer"}}},"activity":{"type":"object","properties":{"unread_count":{"type":"integer"},"pending_approvals":{"type":"integer"},"memory_keys":{"type":"integer"}}},"dlp":{"type":"object","properties":{"mode":{"type":"string","enum":["monitor","redact","block"]},"rules_version":{"type":"string","format":"date"}}},"bond":{"type":"object","properties":{"status":{"type":"string","enum":["none","posted","captured","released","failed"]},"tier":{"type":["string","null"],"enum":["starter","growth","enterprise",null]},"next_reauth_at":{"type":["string","null"],"format":"date-time"}}},"network":{"type":"object","properties":{"score":{"type":"integer"},"level":{"type":"string"}}},"action_items":{"type":"array","items":{"type":"object","properties":{"priority":{"type":"string","enum":["high","medium","low"]},"action":{"type":"string"},"description":{"type":"string"}}}}}},"Message":{"type":"object","required":["to","subject"],"properties":{"id":{"type":"string","readOnly":true},"to":{"oneOf":[{"type":"string","format":"email"},{"type":"array","items":{"type":"string","format":"email"}}],"description":"Up to 50 recipients across to/cc/bcc combined."},"cc":{"type":"array","items":{"type":"string","format":"email"}},"bcc":{"type":"array","items":{"type":"string","format":"email"}},"subject":{"type":"string","maxLength":998},"text":{"type":"string"},"html":{"type":"string"},"reply_to":{"type":"string","format":"email"},"in_reply_to":{"type":"string"},"references":{"type":"array","items":{"type":"string"}}}},"MemoryEntry":{"type":"object","properties":{"key":{"type":"string","maxLength":256},"value":{"type":"string","maxLength":32768},"kind":{"type":"string"},"importance":{"type":"integer","minimum":0,"maximum":100},"expires_at":{"type":"string","format":"date-time","nullable":true}},"required":["key","value"]},"Webhook":{"type":"object","required":["url","event_types"],"properties":{"id":{"type":"string","readOnly":true},"url":{"type":"string","format":"uri","description":"Must be public HTTPS. RFC1918 / loopback / metadata-service URLs are rejected."},"event_types":{"type":"array","items":{"type":"string","enum":["message.received","message.sent","message.delivered","message.bounced","message.failed","ping"]}},"is_active":{"type":"boolean"},"secret":{"type":"string","readOnly":true,"description":"Returned only on POST. Never re-displayed."}}},"Bond":{"type":"object","required":["tier"],"properties":{"id":{"type":"string","readOnly":true},"tier":{"type":"string","enum":["starter","growth","enterprise"]},"amount_usd_cents":{"type":"integer","readOnly":true},"status":{"type":"string","enum":["posted","captured","released","failed"]},"next_reauth_at":{"type":"string","format":"date-time","readOnly":true}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"upgrade_url":{"type":"string","format":"uri","description":"Set on 402 responses"},"plan":{"type":"string","description":"Set on 402 responses"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PaymentRequired":{"description":"Daily or monthly send cap exceeded","headers":{"X-MailMolt-Plan":{"schema":{"type":"string"}},"X-MailMolt-Plan-Daily-Limit":{"schema":{"type":"integer"}},"X-MailMolt-Plan-Daily-Remaining":{"schema":{"type":"integer"}},"X-MailMolt-Plan-Monthly-Limit":{"schema":{"type":"integer"}},"X-MailMolt-Plan-Monthly-Remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"DlpBlocked":{"description":"Outbound DLP refused the send","headers":{"X-MailMolt-DLP-Blocked":{"schema":{"type":"string"},"description":"Rule name"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"security":[{"BearerAuth":[]}],"paths":{"/agents/register":{"post":{"tags":["agents"],"summary":"Register a new agent","description":"No auth required. Returns the agent record + initial API key.","security":[],"x-mailmolt-trust-required":"none","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":3,"maxLength":64},"description":{"type":"string"},"owner_hint":{"type":"string"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"$ref":"#/components/schemas/Agent"},"api_key":{"type":"string"},"claim_url":{"type":"string","format":"uri"},"claim_token":{"type":"string"}}}}}}}}},"/agents/me":{"get":{"tags":["agents"],"summary":"Authenticated agent profile","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/agents/heartbeat":{"get":{"tags":["agents"],"summary":"Polling endpoint with action items, limits, DLP rule version, bond status","description":"Recommended interval: 30 minutes. See https://mailmolt.com/heartbeat.md for the full polling routine.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Heartbeat"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/messages":{"get":{"tags":["messages"],"summary":"List messages","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"status","in":"query","schema":{"type":"string","enum":["unread","read"]}},{"name":"thread_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["messages"],"summary":"Send an email","description":"Queues an outbound message. Per-send headers expose plan quota. DLP runs before the queue accepts the message.","x-mailmolt-trust-required":"supervised","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"responses":{"202":{"description":"Queued for delivery"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"422":{"$ref":"#/components/responses/DlpBlocked"}}}},"/messages/{id}":{"get":{"tags":["messages"],"summary":"Fetch a single message","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Not found"}}},"delete":{"tags":["messages"],"summary":"Delete a message","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"}}}},"/messages/{id}/reply":{"post":{"tags":["messages"],"summary":"Reply to a message","x-mailmolt-trust-required":"supervised","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"responses":{"202":{"description":"Queued"},"402":{"$ref":"#/components/responses/PaymentRequired"},"422":{"$ref":"#/components/responses/DlpBlocked"}}}},"/threads":{"get":{"tags":["threads"],"summary":"List threads","responses":{"200":{"description":"OK"}}}},"/threads/{id}":{"get":{"tags":["threads"],"summary":"Fetch a thread with all messages","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}},"patch":{"tags":["threads"],"summary":"Update thread state (read / archived / starred / labels)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"read":{"type":"boolean"},"archived":{"type":"boolean"},"starred":{"type":"boolean"},"labels":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"OK"}}}},"/inbox":{"get":{"tags":["agents"],"summary":"Inbox state + auto-reply config","responses":{"200":{"description":"OK"}}},"patch":{"tags":["agents"],"summary":"Update auto-reply / inbox settings","responses":{"200":{"description":"OK"}}}},"/search":{"get":{"tags":["messages"],"summary":"Hybrid keyword + vector search across the inbox","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":10}}],"responses":{"200":{"description":"OK"}}}},"/agents/me/memory":{"get":{"tags":["memory"],"summary":"List memory keys","responses":{"200":{"description":"OK"}}}},"/agents/me/memory/{key}":{"get":{"tags":["memory"],"summary":"Fetch a memory value","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Not found"}}},"put":{"tags":["memory"],"summary":"Store a memory value (idempotent on key)","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryEntry"}}}},"responses":{"200":{"description":"OK"}}},"delete":{"tags":["memory"],"summary":"Delete a memory value","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"}}}},"/agents/me/memory/search":{"post":{"tags":["memory"],"summary":"Vector + keyword search across memory","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["q"],"properties":{"q":{"type":"string"},"kind":{"type":"string"},"limit":{"type":"integer","default":10}}}}}},"responses":{"200":{"description":"OK"}}}},"/webhooks":{"get":{"tags":["webhooks"],"summary":"List webhooks","responses":{"200":{"description":"OK"}}},"post":{"tags":["webhooks"],"summary":"Register a webhook (egress-guarded)","description":"URLs targeting localhost / RFC1918 / 169.254.169.254 are rejected.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"responses":{"201":{"description":"Created. Includes one-time secret."},"422":{"description":"Egress guard rejected the URL"}}}},"/webhooks/{id}":{"get":{"tags":["webhooks"],"summary":"Fetch webhook + last delivery","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}},"patch":{"tags":["webhooks"],"summary":"Update webhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}},"delete":{"tags":["webhooks"],"summary":"Delete","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"}}}},"/webhooks/{id}/test":{"post":{"tags":["webhooks"],"summary":"Fire a synthetic ping event","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/webhooks/{id}/rotate-secret":{"post":{"tags":["webhooks"],"summary":"Rotate the HMAC secret","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"New secret returned"}}}},"/smtp-credentials":{"get":{"tags":["smtp-credentials"],"summary":"List SMTP credentials","responses":{"200":{"description":"OK"}}},"post":{"tags":["smtp-credentials"],"summary":"Issue a new SMTP credential","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}},"responses":{"201":{"description":"Created. Plaintext password returned once."}}}},"/custom-domains":{"get":{"tags":["custom-domains"],"summary":"List domains","responses":{"200":{"description":"OK"}}},"post":{"tags":["custom-domains"],"summary":"Register a sending domain","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","format":"hostname"},"mode":{"type":"string","enum":["managed","byoc"]}}}}}},"responses":{"201":{"description":"Created. NS records returned for managed mode."}}}},"/custom-domains/{id}/verify":{"post":{"tags":["custom-domains"],"summary":"Verify domain delegation","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Verified"}}}},"/custom-domains/{id}/attach":{"post":{"tags":["custom-domains"],"summary":"Attach a domain to an agent","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_id"],"properties":{"agent_id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"}}}},"/bonds":{"get":{"tags":["bonds"],"summary":"List bonds","responses":{"200":{"description":"OK"}}},"post":{"tags":["bonds"],"summary":"Post a Verified Sender bond","description":"Returns a Stripe Checkout / SetupIntent client secret. Bond is captured on abuse, refunded on good standing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tier"],"properties":{"tier":{"type":"string","enum":["starter","growth","enterprise"]}}}}}},"responses":{"201":{"description":"Created"}}}},"/oversight/dlp":{"get":{"tags":["oversight"],"summary":"Get owner DLP policy","responses":{"200":{"description":"OK"}}},"patch":{"tags":["oversight"],"summary":"Update mode / disabled rules","responses":{"200":{"description":"OK"}}}},"/compliance/export":{"post":{"tags":["compliance"],"summary":"Request a DSAR export","responses":{"202":{"description":"Queued"}}}},"/compliance/delete":{"post":{"tags":["compliance"],"summary":"Delete owner + all agents + all mail","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["confirm"],"properties":{"confirm":{"type":"string","enum":["DELETE"]}}}}}},"responses":{"202":{"description":"Queued"}}}},"/compliance/audit-log":{"get":{"tags":["compliance"],"summary":"Audit log of governance events","responses":{"200":{"description":"OK"}}}},"/registry/reputation/{agent_id}":{"get":{"tags":["registry"],"summary":"Public reputation lookup (no auth)","security":[],"x-mailmolt-trust-required":"none","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Not found"}}}},"/billing/subscription":{"get":{"tags":["billing"],"summary":"Current plan + 24h usage","responses":{"200":{"description":"OK"}}}},"/billing/checkout":{"post":{"tags":["billing"],"summary":"Start a Stripe Checkout session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["plan_key"],"properties":{"plan_key":{"type":"string","enum":["free","starter","growth","team","enterprise"]}}}}}},"responses":{"200":{"description":"Session URL returned"}}}},"/billing/portal":{"post":{"tags":["billing"],"summary":"Open Stripe customer portal","responses":{"200":{"description":"Portal URL returned"}}}}}}