{"openapi":"3.1.0","info":{"title":"s7ortlynk.com Mail API","description":"Persistent mailboxes on **s7ortlynk.com**. This service receives mail;\nit does not send.\n\nCreate an address, receive mail at it, and read it back — over HTTP, in the\nwebmail, or through the Telegram bot. The written guide is at [/docs](/docs).\n\n**Authentication:** every endpoint except `/health` needs the header\n`X-API-Key: <key>`. Send `/apikey` to the Telegram bot to get yours.\n\n**Waiting for a signup code:** create an address, trigger the email, then call\n`GET /api/v1/messages/wait`. It blocks until the mail lands and returns it\nwith any verification codes already extracted into `codes`.\n\n**Web view:** every message carries a `preview_url` that opens it as a web\npage without login.","version":"1.2.0"},"paths":{"/api/v1/health":{"get":{"tags":["system"],"summary":"Health","description":"Unauthenticated liveness probe.","operationId":"health_api_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthOut"}}}}}}},"/api/v1/me":{"get":{"tags":["system"],"summary":"Me","description":"The account this API key belongs to.","operationId":"me_api_v1_me_get","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/mailboxes":{"get":{"tags":["mailboxes"],"summary":"List Mailboxes","description":"Every address you own, with its unread count.","operationId":"list_mailboxes_api_v1_mailboxes_get","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MailboxOut"},"title":"Response List Mailboxes Api V1 Mailboxes Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["mailboxes"],"summary":"Create Mailbox","description":"Provision an address. Omit `local_part` to get a random one.","operationId":"create_mailbox_api_v1_mailboxes_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/mailboxes/{ref}":{"get":{"tags":["mailboxes"],"summary":"Get Mailbox","description":"Look one up by id, address, or local part.","operationId":"get_mailbox_api_v1_mailboxes__ref__get","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","description":"Mailbox id, full address, or local part.","title":"Ref"},"description":"Mailbox id, full address, or local part."},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["mailboxes"],"summary":"Delete Mailbox","description":"Delete the mailbox, its mail, and its attachment files.","operationId":"delete_mailbox_api_v1_mailboxes__ref__delete","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","description":"Mailbox id, full address, or local part.","title":"Ref"},"description":"Mailbox id, full address, or local part."},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/mailboxes/{ref}/mute":{"post":{"tags":["mailboxes"],"summary":"Mute","description":"Stop Telegram notifications for this mailbox.","operationId":"mute_api_v1_mailboxes__ref__mute_post","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","description":"Mailbox id, full address, or local part.","title":"Ref"},"description":"Mailbox id, full address, or local part."},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/mailboxes/{ref}/unmute":{"post":{"tags":["mailboxes"],"summary":"Unmute","description":"Resume Telegram notifications.","operationId":"unmute_api_v1_mailboxes__ref__unmute_post","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","description":"Mailbox id, full address, or local part.","title":"Ref"},"description":"Mailbox id, full address, or local part."},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/messages":{"get":{"tags":["messages"],"summary":"List Messages","description":"Messages across your mailboxes, newest first.","operationId":"list_messages_api_v1_messages_get","parameters":[{"name":"mailbox","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Id, address or local part.","title":"Mailbox"},"description":"Id, address or local part."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"unread_only","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Unread Only"}},{"name":"since_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"Only ids above this.","title":"Since Id"},"description":"Only ids above this."},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MessageSummary"},"title":"Response List Messages Api V1 Messages Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/messages/wait":{"get":{"tags":["messages"],"summary":"Wait For Message","description":"Block until the next message arrives, then return it.\n\nBuilt for signup flows: create an address, trigger the email, call this,\nand read the code straight out of `codes`. Returns `null` on timeout, so\na client can simply call it again.","operationId":"wait_for_message_api_v1_messages_wait_get","parameters":[{"name":"mailbox","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Id, address or local part.","title":"Mailbox"},"description":"Id, address or local part."},{"name":"since_id","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Return the first id above this.","default":0,"title":"Since Id"},"description":"Return the first id above this."},{"name":"timeout","in":"query","required":false,"schema":{"type":"number","maximum":120.0,"minimum":1.0,"default":30.0,"title":"Timeout"}},{"name":"mark","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Mark"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/MessageDetail"},{"type":"null"}],"title":"Response Wait For Message Api V1 Messages Wait Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/messages/{message_id}":{"get":{"tags":["messages"],"summary":"Get Message","description":"One message: headers, both bodies, attachments, codes and links.","operationId":"get_message_api_v1_messages__message_id__get","parameters":[{"name":"message_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"title":"Message Id"}},{"name":"mark","in":"query","required":false,"schema":{"type":"boolean","description":"Mark the message read.","default":true,"title":"Mark"},"description":"Mark the message read."},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["messages"],"summary":"Delete Message","description":"Delete a message and its attachment files.","operationId":"delete_message_api_v1_messages__message_id__delete","parameters":[{"name":"message_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"title":"Message Id"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/messages/{message_id}/html":{"get":{"tags":["messages"],"summary":"Get Message Html","description":"Sanitised body, safe to inject into a page.\n\nScripts, event handlers and dangerous URL schemes are stripped; `cid:`\nimages are inlined; remote images are blocked unless `images=true`.\n`available` says which views the message actually has, so a client can\noffer an HTML / Text switch only when both exist.","operationId":"get_message_html_api_v1_messages__message_id__html_get","parameters":[{"name":"message_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"title":"Message Id"}},{"name":"view","in":"query","required":false,"schema":{"enum":["auto","html","text"],"type":"string","description":"Which part to render. `auto` picks HTML when the mail has it.","default":"auto","title":"View"},"description":"Which part to render. `auto` picks HTML when the mail has it."},{"name":"images","in":"query","required":false,"schema":{"type":"boolean","description":"Also load remote images.","default":false,"title":"Images"},"description":"Also load remote images."},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenderedBody"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/messages/{message_id}/raw":{"get":{"tags":["messages"],"summary":"Get Message Raw","description":"The original RFC 822 bytes, headers included.","operationId":"get_message_raw_api_v1_messages__message_id__raw_get","parameters":[{"name":"message_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"title":"Message Id"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/attachments/{attachment_id}":{"get":{"tags":["messages","attachments"],"summary":"Download Attachment","description":"Download one attachment with its original filename.","operationId":"download_attachment_api_v1_attachments__attachment_id__get","parameters":[{"name":"attachment_id","in":"path","required":true,"schema":{"type":"integer","minimum":1,"title":"Attachment Id"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AttachmentOut":{"properties":{"id":{"type":"integer","title":"Id"},"filename":{"type":"string","title":"Filename"},"content_type":{"type":"string","title":"Content Type"},"size_bytes":{"type":"integer","title":"Size Bytes"},"is_inline":{"type":"boolean","title":"Is Inline"}},"type":"object","required":["id","filename","content_type","size_bytes","is_inline"],"title":"AttachmentOut"},"AuthOut":{"properties":{"spf":{"type":"string","title":"Spf","default":""},"dkim":{"type":"string","title":"Dkim","default":""},"dmarc":{"type":"string","title":"Dmarc","default":""},"verdict":{"type":"string","title":"Verdict","description":"\"pass\": the From domain is verified. \"fail\": the domain says this mail is not theirs — treat it as forged. \"none\": nothing to check against.","default":""},"tls":{"type":"string","title":"Tls","description":"TLS version of the delivering connection, \"\" if plaintext.","default":""}},"type":"object","title":"AuthOut","description":"Sender-authentication results, checked when the message arrived.\n\n`spf`, `dkim` and `dmarc` are RFC 8601 result words (pass, fail, softfail,\nneutral, none, temperror, permerror). All fields are \"\" for mail stored\nbefore the check existed."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthOut":{"properties":{"ok":{"type":"boolean","title":"Ok"},"domain":{"type":"string","title":"Domain","description":"Domain new addresses are created on."},"domains":{"items":{"type":"string"},"type":"array","title":"Domains","description":"Every domain mail is accepted for."},"version":{"type":"string","title":"Version"},"sending_enabled":{"type":"boolean","title":"Sending Enabled","description":"False when the service only receives."}},"type":"object","required":["ok","domain","version","sending_enabled"],"title":"HealthOut"},"MailboxCreate":{"properties":{"local_part":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Local Part","description":"Leave empty for a randomly generated address."}},"type":"object","title":"MailboxCreate"},"MailboxOut":{"properties":{"id":{"type":"integer","title":"Id"},"address":{"type":"string","title":"Address"},"local_part":{"type":"string","title":"Local Part"},"notify":{"type":"boolean","title":"Notify"},"created_at":{"type":"string","title":"Created At"},"unread":{"type":"integer","title":"Unread","description":"Unread messages in this mailbox.","default":0}},"type":"object","required":["id","address","local_part","notify","created_at"],"title":"MailboxOut"},"MeOut":{"properties":{"id":{"type":"integer","title":"Id"},"telegram_id":{"type":"integer","title":"Telegram Id"},"username":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Username"},"is_admin":{"type":"boolean","title":"Is Admin"},"mailbox_count":{"type":"integer","title":"Mailbox Count"}},"type":"object","required":["id","telegram_id","username","is_admin","mailbox_count"],"title":"MeOut"},"MessageDetail":{"properties":{"id":{"type":"integer","title":"Id"},"mailbox_id":{"type":"integer","title":"Mailbox Id"},"msg_from":{"type":"string","title":"Msg From"},"subject":{"type":"string","title":"Subject"},"size_bytes":{"type":"integer","title":"Size Bytes"},"received_at":{"type":"string","title":"Received At"},"is_read":{"type":"boolean","title":"Is Read"},"attachment_count":{"type":"integer","title":"Attachment Count"},"auth_verdict":{"type":"string","title":"Auth Verdict","description":"Sender verification: \"pass\", \"fail\" (likely forged), \"none\" or \"\" (not checked).","default":""},"preview_url":{"type":"string","title":"Preview Url","description":"Signed link that opens this message as a web page without login; expires after PREVIEW_TTL_DAYS.","default":""},"auth":{"$ref":"#/components/schemas/AuthOut"},"msg_to":{"type":"string","title":"Msg To"},"body_text":{"type":"string","title":"Body Text"},"body_html":{"type":"string","title":"Body Html"},"attachments":{"items":{"$ref":"#/components/schemas/AttachmentOut"},"type":"array","title":"Attachments"},"codes":{"items":{"type":"string"},"type":"array","title":"Codes","description":"Verification codes found in the message, best guess first."},"links":{"items":{"type":"string"},"type":"array","title":"Links"}},"type":"object","required":["id","mailbox_id","msg_from","subject","size_bytes","received_at","is_read","attachment_count","msg_to","body_text","body_html","attachments"],"title":"MessageDetail"},"MessageSummary":{"properties":{"id":{"type":"integer","title":"Id"},"mailbox_id":{"type":"integer","title":"Mailbox Id"},"msg_from":{"type":"string","title":"Msg From"},"subject":{"type":"string","title":"Subject"},"size_bytes":{"type":"integer","title":"Size Bytes"},"received_at":{"type":"string","title":"Received At"},"is_read":{"type":"boolean","title":"Is Read"},"attachment_count":{"type":"integer","title":"Attachment Count"},"auth_verdict":{"type":"string","title":"Auth Verdict","description":"Sender verification: \"pass\", \"fail\" (likely forged), \"none\" or \"\" (not checked).","default":""},"preview_url":{"type":"string","title":"Preview Url","description":"Signed link that opens this message as a web page without login; expires after PREVIEW_TTL_DAYS.","default":""}},"type":"object","required":["id","mailbox_id","msg_from","subject","size_bytes","received_at","is_read","attachment_count"],"title":"MessageSummary"},"RenderedBody":{"properties":{"id":{"type":"integer","title":"Id"},"html":{"type":"string","title":"Html"},"format":{"type":"string","title":"Format","description":"View actually rendered: \"html\", \"text\" or \"empty\"."},"available":{"items":{"type":"string"},"type":"array","title":"Available","description":"Parts the message really has, e.g. [\"html\", \"text\"]."},"blocked_images":{"type":"integer","title":"Blocked Images"},"inlined_images":{"type":"integer","title":"Inlined Images"}},"type":"object","required":["id","html","format","blocked_images","inlined_images"],"title":"RenderedBody"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"tags":[{"name":"system","description":"Health and account."},{"name":"mailboxes","description":"Create and manage addresses."},{"name":"messages","description":"Read, wait for and delete mail."},{"name":"attachments","description":"Download attachment files."}]}