{"openapi":"3.1.0","info":{"title":"Freedom Agent Mail API","version":"1.0.0","summary":"Free, receive-only, disposable email inboxes for AI agents and humans.","description":"Create an inbox, use its address (for example in a sign-up form), then wait for mail. No sign-up or API key: create an inbox with POST /accounts, get a bearer token from POST /token. Messages include extracted one-time codes and verification links. Inboxes are kept until deleted; messages are deleted after 30 days. Inboxes cannot send email.\n\nSend `Accept: application/json` for the plain JSON shapes described here; without it, responses use JSON-LD (Hydra), where collections are wrapped as `{\"hydra:member\": [...], \"hydra:totalItems\": n}`.\n\nAn MCP server (Streamable HTTP) with the same features is at https://freedomagentmail.us/mcp?ref=openapi, and a short guide for language models is at https://freedomagentmail.us/llms.txt."},"externalDocs":{"description":"Guide for AI agents","url":"https://freedomagentmail.us/llms.txt"},"servers":[{"url":"https://freedomagentmail.us"}],"security":[{"bearerAuth":[]}],"paths":{"/domains":{"get":{"operationId":"listDomains","summary":"List the domains inboxes can be created on","security":[],"responses":{"200":{"description":"Available domains","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Domain"}}}}}}}},"/accounts":{"post":{"operationId":"createInbox","summary":"Create an inbox","description":"Pick any free username on an available domain, and any password. Rate-limited per IP address.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credentials"}}}},"responses":{"201":{"description":"The new inbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"422":{"description":"Invalid or taken address, or bad password","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/token":{"post":{"operationId":"login","summary":"Get a bearer token for an inbox","description":"Tokens expire; when one does, call this again with the same address and password.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Credentials"}}}},"responses":{"200":{"description":"Token","content":{"application/json":{"schema":{"type":"object","required":["token","id"],"properties":{"token":{"type":"string"},"id":{"type":"string","description":"Account id"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/me":{"get":{"operationId":"getMe","summary":"Get the current inbox","responses":{"200":{"description":"The inbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/accounts/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"operationId":"getAccount","summary":"Get an inbox","responses":{"200":{"description":"The inbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"operationId":"deleteInbox","summary":"Delete an inbox and all its mail","responses":{"204":{"description":"Deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/messages/wait":{"get":{"operationId":"waitForMessages","summary":"Wait for new mail (long poll)","description":"Returns unread messages as soon as any arrive, or an empty list after the timeout, and marks them read. Use format=agent for a compact view with codes and verification links.","parameters":[{"name":"timeout","in":"query","schema":{"type":"integer","minimum":0,"maximum":60,"default":30},"description":"Seconds to wait"},{"name":"format","in":"query","schema":{"type":"string","enum":["agent"]},"description":"Compact agent format"}],"responses":{"200":{"description":"New messages (empty if none arrived)","content":{"application/json":{"schema":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/AgentMessage"},{"$ref":"#/components/schemas/Message"}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/messages":{"get":{"operationId":"listMessages","summary":"List messages, newest first (30 per page)","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"Messages","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MessageSummary"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/messages/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"operationId":"getMessage","summary":"Read a message (marks it read)","responses":{"200":{"description":"The message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"markMessage","summary":"Mark a message read or unread","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"seen":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"The message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"operationId":"deleteMessage","summary":"Delete a message","responses":{"204":{"description":"Deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/messages/{id}/download":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"operationId":"downloadMessage","summary":"Download the raw message (.eml)","responses":{"200":{"description":"Raw RFC 822 message","content":{"message/rfc822":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/messages/{id}/attachment/{attachmentId}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"attachmentId","in":"path","required":true,"schema":{"type":"string","example":"ATTACH000001"}}],"get":{"operationId":"downloadAttachment","summary":"Download an attachment","responses":{"200":{"description":"Attachment bytes","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/sources/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"operationId":"getMessageSource","summary":"Get the raw message source as JSON","responses":{"200":{"description":"Source","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"downloadUrl":{"type":"string"},"data":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token from POST /token"}},"responses":{"Unauthorized":{"description":"Missing, invalid or expired token, or wrong credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests from this IP address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Credentials":{"type":"object","required":["address","password"],"properties":{"address":{"type":"string","format":"email","example":"someone123@freedomagentmail.us","description":"Username of 3-64 letters, digits, dots, hyphens or underscores, on a domain from GET /domains"},"password":{"type":"string","minLength":6,"maxLength":128}}},"Domain":{"type":"object","properties":{"id":{"type":"string"},"domain":{"type":"string","example":"freedomagentmail.us"},"isActive":{"type":"boolean"},"isPrivate":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Account":{"type":"object","properties":{"id":{"type":"string"},"address":{"type":"string","format":"email"},"quota":{"type":"integer","description":"Storage quota in bytes"},"used":{"type":"integer","description":"Bytes used"},"isDisabled":{"type":"boolean"},"isDeleted":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Address":{"type":"object","properties":{"address":{"type":"string"},"name":{"type":"string"}}},"Link":{"type":"object","properties":{"url":{"type":"string"},"text":{"type":"string"},"kind":{"type":"string","enum":["verification","other","unsubscribe"]}}},"MessageSummary":{"type":"object","properties":{"id":{"type":"string"},"accountId":{"type":"string"},"msgid":{"type":"string"},"from":{"$ref":"#/components/schemas/Address"},"to":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"subject":{"type":"string"},"intro":{"type":"string","description":"First part of the text"},"seen":{"type":"boolean"},"isDeleted":{"type":"boolean"},"hasAttachments":{"type":"boolean"},"size":{"type":"integer"},"downloadUrl":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"codes":{"type":"array","items":{"type":"string"},"description":"One-time codes found in the message"}}},"Message":{"allOf":[{"$ref":"#/components/schemas/MessageSummary"},{"type":"object","properties":{"cc":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"bcc":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"flagged":{"type":"boolean"},"retentionDate":{"type":"string","format":"date-time","description":"When the message will be deleted"},"text":{"type":"string"},"html":{"type":"array","items":{"type":"string"}},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string"},"contentType":{"type":"string"},"size":{"type":"integer"},"downloadUrl":{"type":"string"}}}},"links":{"type":"array","items":{"$ref":"#/components/schemas/Link"}}}}]},"AgentMessage":{"type":"object","description":"Compact view returned by GET /messages/wait?format=agent","properties":{"id":{"type":"string"},"from":{"type":"string"},"subject":{"type":"string"},"receivedAt":{"type":"string","format":"date-time"},"codes":{"type":"array","items":{"type":"string"}},"verificationLinks":{"type":"array","items":{"type":"string"}},"otherLinks":{"type":"array","items":{"type":"string"}},"text":{"type":"string","description":"Plain text, truncated after 4000 characters"},"attachments":{"type":"array","items":{"type":"string"}}}},"Error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"detail":{"type":"string"},"status":{"type":"integer"}}},"ValidationError":{"type":"object","properties":{"detail":{"type":"string"},"status":{"type":"integer"},"violations":{"type":"array","items":{"type":"object","properties":{"propertyPath":{"type":"string"},"message":{"type":"string"}}}}}}}}}