{"openapi":"3.0.0","info":{"version":"1.0.8","title":"mailsac API Specification","x-logo":{"url":"/img/mailsac-logo-v2.png","altText":"mailsac logo"},"description":"## About the API\n\nThe Mailsac API allows for interacting with Mailsac services, including checking email,\nemail validations, setting up forwarding addresses, receiving web socket email messages,\nand sending outbound mail.\n\n[**Get a free API key**](https://mailsac.com/api-keys)\n\nTest the Mailsac API online:\n\n* [**Swagger UI Explorer** →](https://mailsac.com/docs/swagger)\n\n**Base API Endpoint**:\n\n* `https://mailsac.com/api/`\n* _All API documentation is relative to this endpoint._\n\n**OpenAPI Spec**:\n\n* [Download JSON](https://mailsac.com/openapi.json)\n* [Download YAML](https://mailsac.com/openapi.yml)\n\n\n### Support and Resources\n\n* [npm Node.js and Browser library - @mailsac/api](https://www.npmjs.com/package/@mailsac/api)\n* [Full Documentation and Guides](https://docs.mailsac.com)\n* [Community Support and Discussion Forums](https://forum.mailsac.com/forums/)\n* [Web socket example in Node.js - ruffrey](https://github.com/ruffrey/mailsac-node-websocket-example)\n\nPaid Email Support, Pre-Sales\n > [email protected]\n\n[Terms of Service](https://docs.mailsac.com/en/latest/about/terms_of_service.html)\n\n[Privacy Policy](https://docs.mailsac.com/en/latest/about/privacy_policy.html)\n"},"servers":[{"url":"https://mailsac.com/api"}],"tags":[{"name":"Authentication Guide","description":"[API keys](https://mailsac.com/api-keys) are used to establish your identity with the Mailsac API.\n\nKeys can be passed as a header, querystring parameter, or request body json field.\n\n### API Key Format\n\nExample Key:\n\n> `k_eoj1mn7x5y61w0egs25j6xrv`\n\nAPI keys are alphanumeric, cryptographically-random tokens.\n\n\n## Get an API Key\n\n[All subscription levels, including free accounts, may create API keys.](https://mailsac.com/v2/credentials/keys)\nAPI keys cannot be managed by other API keys.\n\nGo to the [Credentials > API Keys & Users](https://mailsac.com/v2/credentials/keys) from the Dashboard to manage your account's API keys.\n\n### Multiple Keys\n\nThe Free and Indie tiers allow just one API key. That works fine for an individual developer or QA tester.\n\n[Some subscription tiers](https://mailasc.com/pricing) can create multiple API keys, and name each one - useful for managing many apps, users, and deployment environments.\n\nThere's no limit on the number of API credentials which can be generated for the tiers allowing more than one to be created.\n\n### API Website Logins\n\n[Some subscription tiers](https://mailasc.com/pricing) also allow API credentials to be used to log into the website user interface.\n\n\n## Auth Option 1: HTTP Header\n\nUse the API key as a request header named `Mailsac-Key`.\n\n```\nHTTP/1.x 200 OK\nGET /api/addresses/[email protected]/messages\nHost: mailsac.com\nMailsac-Key: k_eoj1mn7x5y61w0egs25j6xrv\n```\n\nCheck that your API key is working:\n\n```bash\ncurl --header \"Mailsac-Key: k_eoj1mn7x5y61w0egs25j6xrv\" https://mailsac.com/api/me\n```\n\nwhich will return a JSON object with your account details.\n\n```json\n{\n \"_id\": \"myaccount_name_here\",\n \"email\": \"[email protected]\"\n\n /* more props */\n}\n```\n\n## Auth Option 2: Query String Parameter\n\nIn the query section of the URL (after `?`) add a parameter for `_mailsacKey`.\n\n```bash\ncurl https://mailsac.com/api/addresses/[email protected]/messages?_mailsacKey=k_eoj1mn7x5y61w0egs25j6xrv\n```\n\nNote: this is the least secure option. We recommend using Option 1: HTTP Header.\n\n## Auth Option 3: Request JSON Body\n\nDuring a POST, PATCH, or PUT request, add a JSON field for `_mailsacKey`.\n\n```json\n{\n \"_mailsacKey\": \"k_eoj1mn7x5y61w0egs25j6xrv\",\n\n /* more POST, PUT props etc. */\n}\n```\n"},{"x-displayName":"Email Messages API","name":"Messages","description":"This section of the API deals with email messages. Mailsac parses messages into many formats,\nand can return various bits of metadata, like the sender, recipients, subject, headers, and\neven all the external links.\n\n#### Permissions and Disposability\n\nBy default, all emails sent to Mailsac are accepted and public. They are recycled regularly unless starred.\n\nSetting up a _custom domain_ or _private forwarding address_ means only you can see messages sent to it.\n\nAnyone can make API requests to view messages on a public (non-owned) inbox. Anyone can also delete messages from public inboxes.\n\nThrottling is frequently an issue on public inboxes. We strongly recommend using a custom domain or private forwarding address.\n"},{"x-displayName":"Email Addresses API","name":"Addresses","description":"This section contains APIs for creating and deleting enhanced private addresses, and configuring\nmessage routing.\n\nIt is not always necessary to create an email address\nusing these APIs. Mailsac will accept nearly any email. Creating an email address allows it to\nkept private. Its mail can be automatally routed to another email address, web sockets, webhooks,\nand Slack.\n"},{"x-displayName":"Email Validations API","name":"emailValidation","description":"This setion contains APIs to help determine is an email address is a valid format, whether\nit is a disposable address, and the domains or IP addresses it is associated with (in case\nyou want to do your own additional lookups or restrictions).\n\nThere are two routes for validating email addresses.\n\nThe GET route is for quickly testing in a web browser, or for testing one email address at a\ntime. The GET route will return a JSON object.\n\nThe POST route accepts an array of up to 50 email addresses and will return an array.\n"},{"x-displayName":"Domains API","name":"Domains","description":"This section contains APIs for managing custom domains. It is not complete and will be updated\nwith more endpoints soon.\n"},{"x-displayName":"Email Message Attachments","name":"Attachments","description":"This section contains APIs for finding and downloading email message attachments.\n"},{"x-displayName":"User Account API","name":"Account","description":"This section contains APIs related to the current user and account.\n"},{"x-displayName":"Email Stats API","name":"messageStats","description":"This section contains APIs for researching public disposable email. It may be most relevant for\nemail security researchers.\n"}],"paths":{"/addresses":{"get":{"operationId":"ListAddresses","tags":["Addresses"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"List all enhanced email addresses","description":"Get an array of enhanced private inbox address objects for the account.\n\nThese addresses must be setup (\"reserved\") using `POST /api/addresses/:email`, or\n[on the Add Email Address page](https://mailsac.com/private-address).\n","responses":{"200":{"description":"List of enhanced address objects","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailAddressList"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/addresses/{email}":{"parameters":[{"$ref":"#/components/parameters/EmailString"}],"get":{"operationId":"GetAddress","tags":["Addresses"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"Fetch an address or check if it is reserved","responses":{"200":{"description":"Returns an object if owned by the current account, OR is not owned. Includes the `encryptedInbox` field. If not owned, will omit the `owner` key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailAddress"}}}},"401":{"description":"Returns 401 if owned by another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseBody"}}}}}},"post":{"operationId":"CreateAddress","tags":["Addresses"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"Reserve (create/own) a private email address","description":"Sets the email address private and \"owned\" by the account. All messages which already exist,\nand any future messages which are received, will be private to this account only.\n\nAn email address must be reserved to be able to forward messages to another email address,\nSlack, web sockets, or webhooks. Public email addresses, and private email addresses under\na custom domain, are not routeable.\n","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePrivateAddressForwarding"}}}},"responses":{"200":{"description":"Returns the newly created email address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailAddress"}}}},"400":{"description":"Already reserved by the current user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseBody"}}}},"401":{"description":"Owned by another account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseBody"}}}}}},"put":{"operationId":"UpdateAddress","tags":["Addresses"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"Update private email address forwarding and metadata","description":"For a private email address, set it to forward to another place.\n\nIt can be forwarded to another email (with `via mailsac` indicator), to a websocket, to a webhook,\nor to a Slack channel.\n","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePrivateAddressForwarding"}}}},"responses":{"200":{"description":"email forwarding successfully configured"},"401":{"$ref":"#/components/responses/UnauthorizedError"}}},"delete":{"operationId":"DeleteAddress","tags":["Addresses"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"parameters":[{"$ref":"#/components/parameters/DeleteAddressMessagesFlag"}],"summary":"Release an enhanced email address","description":"Removes this enhanced private address from ownership by the account. Any email received to the\naddress's inbox will be public in the future, unless the address was under a custom domain\nwhich is set private.\n","responses":{"200":{"description":"successfully released address"},"400":{"description":"Not currently owned by the current account, or already deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseBody"}}}},"401":{"description":"Owned by another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseBody"}}}}}}},"/addresses/{email}/availability":{"parameters":[{"$ref":"#/components/parameters/EmailString"}],"get":{"operationId":"CheckAvailability","tags":["Addresses"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"Check address ownership","responses":{"200":{"$ref":"#/components/responses/EmailAddressAvailability"}}}},"/private-addresses-bulk":{"post":{"operationId":"CreateAddresses","tags":["Addresses"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"Reserve multiple enhanced addresses","description":"Reserves multiple enhanced private addresses. The max addresses per request is 100.\n\nIt is not necessary to create enhanced addresses before receiving email. Enhanced addresses\nare only necessary to forward messages to another email address, Slack, web sockets, webhooks,\nor fetch messages over POP3.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"addresses":{"$ref":"#/components/schemas/EmailStringList"}}}}}},"responses":{"200":{"description":"Returns the newly created email addresses","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailAddressList"}}}},"400":{"description":"Not enough enhanced address credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseBody"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/validations/addresses/{email}":{"parameters":[{"$ref":"#/components/parameters/EmailString"}],"get":{"operationId":"ValidateAddress","tags":["emailValidation"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"Validate an email address and if it is disposable","description":"Determine whether an email address is a valid format, whether it is a disposable address,\nand the domains or IP addresses it is associated with.\n","responses":{"200":{"description":"EmailAddressIntegrity object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailAddressIntegrity"}}}}}}},"/validations/addresses":{"post":{"operationId":"ValidateAddressesBulk","tags":["emailValidation"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"Validate up to 50 email addresses","description":"Determine whether an email address is a valid format, whether it is a disposable address,\nand the domains or IP addresses it is associated with.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"emails":{"$ref":"#/components/schemas/EmailStringList"}}}}}},"responses":{"200":{"description":"Array of EmailAddressIntegrity objects","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailAddressIntegrityList"}}}}}}},"/addresses/{email}/message-count":{"parameters":[{"$ref":"#/components/parameters/EmailString"}],"get":{"operationId":"CountMessages","tags":["Messages"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"Count messages for an email inbox","description":"Get the number of messages for an email inbox address.\n**It is NOT necessary to reserve the address** before using this route. Whether it is an address on a custom domain, or a public domain, or mailsac.com, the mail can be counted as long as nobody else owns it.","responses":{"200":{"description":"Email messages","content":{"application/json":{"schema":{"properties":{"count":{"type":"number","example":3},"inbox":{"type":"string","example":"[email protected]"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/OwnedByAnotherUser"}}}},"/addresses/{email}/messages":{"parameters":[{"$ref":"#/components/parameters/EmailString"},{"$ref":"#/components/parameters/Until"},{"$ref":"#/components/parameters/limit"}],"get":{"operationId":"ListMessages","tags":["Messages"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"List messages for an email inbox","description":"Get a list of messages for the email address. Messages are always **sorted in decending order by when they were received**, with the newest message always in the first position of the array.\n\nThe email message objects are abbreviated to provide basic meta data. To get more information about a specific message, use `GET /api/addresses/{email}/messages/{messageId}`.\n\n**It is NOT necessary to reserve the address** before checking mail! Whether it is an address on a custom domain, or a public domain, or mailsac.com, the mail can be checked with this route.","responses":{"200":{"description":"Email messages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMessageList"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/OwnedByAnotherUser"}}},"delete":{"operationId":"DeleteAllMessages","tags":["Messages"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"Delete all messages for an email inbox","description":"This deletes all messages for a specific email address.\n\nThe address must be an owned address or an address in a owned domain.\nStarred messages will not be deleted. Use `DELETE /addresses/{email}/messages/{messageId}`\nto remove starred messages or unstar the messages before calling this route.\n","responses":{"204":{"description":"All non-starred messages deleted"},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/addresses/starred/messages":{"get":{"operationId":"ListStarredMessages","tags":["Messages"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"List starred (saved) messages on the account","description":"Get a list of messages that have been saved and made private for the entire account using the \"star message\" feature.\n\nMessages recieved via the Capture Service will also show up as starred IF the `capturePrivate` flag on the account is enabled.","responses":{"200":{"description":"List of email messages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMessageList"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/addresses/{email}/messages/{messageId}":{"parameters":[{"$ref":"#/components/parameters/EmailString"},{"$ref":"#/components/parameters/messageId"}],"get":{"operationId":"GetMessageMetadata","tags":["Messages"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"Get email message metadata","description":"Retrieves metadata about a single email message. This route includes additional metadata\nnot available when listing messages, such as parsed links from the text or HTML body, and\nattachment md5sums.\n\nTo get even more information about message attachments, like filenames, see the\nAttachments API.\n\nTo get the entire original SMTP message, see the \"raw\" message route.\n","responses":{"200":{"description":"Email message full object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMessage"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/MessageNotFound"}}},"delete":{"operationId":"DeleteMessage","tags":["Messages"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"Delete an email message","description":"Deletes an individual email message. There is no trash or undo.","responses":{"200":{"description":"deletes an email message","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"$ref":"#/components/schemas/MessageId"},"inbox":{"$ref":"#/components/schemas/EmailString"},"message":{"type":"string","example":"Message was deleted."}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/MessageNotFound"}}}},"/raw/{email}/{messageId}":{"parameters":[{"$ref":"#/components/parameters/EmailString"},{"$ref":"#/components/parameters/messageId"},{"$ref":"#/components/parameters/BrowserDownload"}],"get":{"operationId":"GetFullRawMessage","tags":["Messages"],"summary":"Get original SMTP message","description":"Gets the entire original SMTP message transport - everything that was sent over the network\nto Mailsac's inbound servers, plus any Mailsac-generated `Received` headers, and\nspecial `x-mailsac-*` headers.\n","security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"type":"string","example":"Received: from 107.174.77.77 by frontend1-172-31-29-224 via 172.31.99.99 with\n HTTP id 1xyuM9Oexample for ; Mon Dec 24 2018 15:23:55 UTC\nReceived: from 107.174.66.66 by smtp-in2-172-31-42-57 via 172.31.88.88 (proxy)\n with SMTP id 1xyuM9Oexample for ; Mon, 24 Dec 2018 15:23:55 UTC\nX-Mailsac-Whitelist: [email protected],[email protected],107.174.234.77\nDKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=mailsac.com;\n q=dns/txt; s=mailsacrelay;\n bh=QK4Dkk9a92aiAvanYe/AQdKO2djgexample=;\n h=from:subject:to:mime-version:content-type:list-unsubscribe;\n b=jWPuv7tyPRdH+QBKJdOX5Bxjjy82jaaVPZH5p17prXCoZQXlqg/tbqEiPeU6LiwyWfnWsQZV\n vpeh1taqZq4EqiM+5tjmF7W/exampleo=\nContent-Type: multipart/alternative;\n boundary=\"----sinikael-?=_1-1545665044444.8772521444444\"\nReceived: from frontend2-172-31-99-99 ([54.190.149.200]) with HTTP by\n cranberry; Mon Dec 24 2018 10:23:46 GMT-0500 (Eastern Standard Time)\nReceived: from ruffrey ([email protected]) ([98.208.22.74]) with HTTP id\n fe-zi5dp0gwhaa by frontend2-172-31-37-24 ([54.190.149.200]); Mon Dec 24\n 2018 15:23:46 GMT+0000 (Coordinated Universal Time)\nFrom: [email protected]\nTo: [email protected]\nSubject: test\nMessage-ID: <[email protected]>\nList-Unsubscribe: \nDate: Mon, 24 Dec 2018 15:23:54 +0000\nMIME-Version: 1.0\n\n------sinikael-?=_1-15456650346550.8772521546394454\nContent-Type: text/plain\nContent-Transfer-Encoding: 7bit\n\nhi testing\n\nlet's go\n"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/MessageNotFound"}}}},"/addresses/{email}/messages/{messageId}/headers":{"parameters":[{"$ref":"#/components/parameters/EmailString"},{"$ref":"#/components/parameters/messageId"},{"$ref":"#/components/parameters/BrowserDownload"}],"get":{"operationId":"GetHeaders","tags":["Messages"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"Get parsed message headers","description":"Returns pre-parsed message headers in one of 3 formats - `json`, `json-ordered`, or `plain`.\n\nIf no querystring parameter is provided, the default format will be `json`.\n\nEvery email is different; fields in the below examples are not guaranteed to exist.\n","parameters":[{"name":"messageHeadersFormat","in":"query","required":false,"schema":{"type":"string","enum":["json","json-ordered","plain"]}}],"responses":{"200":{"$ref":"#/components/responses/MessageHeaders"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/MessageNotFound"}}}},"/dirty/{email}/{messageId}":{"parameters":[{"$ref":"#/components/parameters/EmailString"},{"$ref":"#/components/parameters/messageId"},{"$ref":"#/components/parameters/BrowserDownload"}],"get":{"operationId":"GetBodyDirty","tags":["Messages"],"summary":"Get message HTML body (dirty)","description":"Get a message's HTML content.\n\nAttached images are inlined and nothing has been stripped.\n\nWhen no HTML body was sent in the original message, a simple HTML body will be created.\n\nUse the querystring param ?download=1 to trigger file download in browser.\n","security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"responses":{"200":{"description":"OK","content":{"text/html":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/MessageNotFound"}}}},"/body/{email}/{messageId}":{"parameters":[{"$ref":"#/components/parameters/EmailString"},{"$ref":"#/components/parameters/messageId"},{"$ref":"#/components/parameters/BrowserDownload"}],"get":{"operationId":"GetBodySanitized","tags":["Messages"],"summary":"Get the message HTML body (sanitized)","description":"Get safe HTML from an email message. Scripts, images and links are stripped out. This HTML\nis safer to render than the potentially \"dirty\" original HTML.\n\nWhen no HTML body was sent in the original message, a simple HTML body will be created.\n\nUse the querystring param ?download=1 to trigger file download in browser.\n","security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"responses":{"200":{"description":"OK","content":{"text/html":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/MessageNotFound"}}}},"/text/{email}/{messageId}":{"parameters":[{"$ref":"#/components/parameters/EmailString"},{"$ref":"#/components/parameters/messageId"},{"$ref":"#/components/parameters/BrowserDownload"}],"get":{"operationId":"GetBodyPlainText","tags":["Messages"],"summary":"Get message plaintext","description":"Get a message's text content. If the original message only contained HTML, a simple plain\ntext body will be generated.\n\nHTTP links in the plain text email will be available when fetching the message's metadata\nat the `message.links[]` property.\n\nUse the querystring param ?download=1 to trigger file download in browser.\n","security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/MessageNotFound"}}}},"/addresses/{email}/messages/{messageId}/star":{"parameters":[{"$ref":"#/components/parameters/EmailString"},{"$ref":"#/components/parameters/messageId"}],"put":{"operationId":"ToggleMessageStar","tags":["Messages"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"Star (save) a message","description":"Toggle a message's *starred* status so it will not be automatically recycled when the account's\nmessage storage limit is reached.\n\nThere is no PUT body.\n\nIt returns only the message metadata.\n","responses":{"200":{"description":"Toggle starred status to protect from deletion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMessageShort"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/MessageNotFound"}}}},"/addresses/{email}/messages/{messageId}/labels/{label}":{"parameters":[{"$ref":"#/components/parameters/EmailString"},{"$ref":"#/components/parameters/messageId"},{"$ref":"#/components/parameters/Label"}],"put":{"operationId":"AddMessageLabel","tags":["Messages"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"Add a label to a message","description":"To help organize messages and group messages together, add a label to a message. Labels\nare used in the Inbox UI to group messages.\n\nWhen successful, returns 200 with a subset of the message object.\n\nWhen the label already exists on the message, the message is not modified and the API\nendpoint returns 200.\n\nNo PUT body is needed.\n","responses":{"200":{"description":"Sets the specified label on a message.","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"$ref":"#/components/schemas/MessageId"},"labels":{"$ref":"#/components/schemas/MessageLabels"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}},"delete":{"operationId":"DeleteMessageLabel","tags":["Messages"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"Remove a label from a message","description":"Removes a label from a message. Returns 200 with a subset of the message object when successful.\n\nWhen the label did not exists on the message, the message is not modified and the API endpoint returns 200.\n","responses":{"200":{"description":"Removes the label from a message.","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"$ref":"#/components/schemas/MessageId"},"labels":{"$ref":"#/components/schemas/MessageLabels"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/MessageNotFound"}}}},"/addresses/{email}/messages/{messageId}/folder/{folder}":{"parameters":[{"$ref":"#/components/parameters/EmailString"},{"$ref":"#/components/parameters/messageId"},{"$ref":"#/components/parameters/MessageFolder"}],"put":{"operationId":"SetMessageFolder","tags":["Messages"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"Move a message into a folder","description":"Move the message to a different mail folder.\n\nNo new folders can be added. To organize mail, use labels.\n\nNo PUT body is needed.\n","responses":{"200":{"description":"Moved message to folder","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"$ref":"#/components/schemas/MessageId"},"folder":{"$ref":"#/components/schemas/MessageFolder"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/MessageNotFound"}}}},"/addresses/{email}/messages/{messageId}/read/{readBoolean}":{"parameters":[{"$ref":"#/components/parameters/EmailString"},{"$ref":"#/components/parameters/messageId"},{"$ref":"#/components/parameters/readBoolean"}],"put":{"operationId":"SetMessageReadStatus","tags":["Messages"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"Set message read/unread status","description":"Change the read state of a message.\n\nPass `readBoolean` as `true` to mark the message as read, and `false` to mark it as unread.\nThe default for any new message `false` (unread).\n\nNo PUT body is needed.\n","responses":{"200":{"description":"Set read/unread status","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"$ref":"#/components/schemas/MessageId"},"folder":{"$ref":"#/components/schemas/readBoolean"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/MessageNotFound"}}}},"/inbox":{"parameters":[{"$ref":"#/components/parameters/limit"},{"name":"since","in":"query","description":"Only fetch messages since this date","required":false,"schema":{"$ref":"#/components/schemas/Date"}},{"$ref":"#/components/parameters/skip"}],"get":{"operationId":"ListInboxMessages","tags":["Messages"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"Get all account messages paginated","description":"Used by the Inbox UI to display all messages for the account, across all domains and private\naddresses.\n\nReturns email message short metadata, paginated, with the global account unread message count.\n","responses":{"200":{"description":"List of short message metadata objects","content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/EmailMessageListShort"}},"unread":{"type":"integer"},"limit":{"type":"integer"},"skip":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/inbox-filter":{"parameters":[{"name":"andSubjectIncludes","in":"query","description":"Messages must include this text in the subject line","required":false,"schema":{"type":"string"}},{"name":"andFrom","in":"query","description":"Messages must include this text in FROM envelope","required":false,"schema":{"type":"string"}},{"name":"andTo","in":"query","description":"Messages must include this text in TO envelope or the `message.inbox` is equal to this value","required":false,"schema":{"type":"string"}},{"name":"andRead","in":"query","description":"Messages must be read or unread","required":false,"schema":{"type":"boolean"}}],"get":{"operationId":"FilterInboxMessages","tags":["Messages"],"summary":"Filter messages in account by to, from, and/or subject","description":"Filter account messages within the the `to` and `from` `.address` fields, and the\n`subject` line. This differs from `/api/inbox-search` by using logical AND, rather than OR\nin `/api/inbox-search`.\n\nAt least one query condition is required, otherwise a 400 will be returned.\n\nA maximum of 100 results will ever be returned. Refine the query or reduce the number of messages\nin the account to find specific items.\n","security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"responses":{"200":{"description":"Query and search results","content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/EmailMessageListShort"}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/inbox-search":{"parameters":[{"name":"query","in":"query","description":"Searches to, from, and subject for all messages on this account, limited to 100 results.","required":false,"schema":{"type":"string"}}],"get":{"operationId":"SearchInboxMessages","tags":["Messages"],"summary":"Search messages by to, from, and subject","description":"Search all account messages within the the `to` and `from` `.address` fields, and the\n`subject` line. This differs from `/api/inbox-filter` by using logical OR, rather than AND\nin `/api/inbox-filter`.\n\nA maximum of 100 results will ever be returned. Refine the query or reduce the number of messages\nin the account to find specific items.\n","security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"responses":{"200":{"description":"Query and search results","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/EmailMessageListShort"}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/domains":{"get":{"operationId":"ListDomains","tags":["Domains"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"List domains","description":"List custom domains for the account.","responses":{"200":{"description":"Domains list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainsList"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/domains/{domain}":{"get":{"operationId":"GetDomain","tags":["Domains"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"Get domain information","description":"Get information about a configured domain, including the number of messages.","responses":{"200":{"description":"Domain information","content":{"application/json":{"schema":{"properties":{"domain":{"$ref":"#/components/schemas/Domain"},"totalMessages":{"type":"integer"},"catchAllAddress":{"$ref":"#/components/schemas/EmailAddress"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/domains/{domain}/messages":{"parameters":[{"$ref":"#/components/parameters/DomainString"},{"$ref":"#/components/parameters/Until"},{"$ref":"#/components/parameters/limit"}],"get":{"operationId":"ListDomainMessages","tags":["Messages"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"List messages for an domain","description":"Get a list of messages across any inboxes of a domain. Messages are always **sorted in decending order by when they were received**, with the newest message always in the first position of the array.\n\nThe email message objects are abbreviated to provide basic meta data. To get more information about a specific message, use `GET /api/addresses/{email}/messages/{messageId}`.\n\nThe domain must be owned by the account making the request, and have DNS validated.\nPaginate with `until?=` and `limit=`.","responses":{"200":{"description":"Email messages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMessageListShort"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/OwnedByAnotherUser"}}}},"/domains/:domain/privacy/:isPrivateBoolean":{"parameters":[{"$ref":"#/components/parameters/DomainString"},{"in":"path","name":"isPrivateBoolean","description":"boolean indicating private or public messages","required":true,"schema":{"type":"boolean"}}]},"/domains/{domain}/delete-all-domain-mail":{"parameters":[{"$ref":"#/components/parameters/DomainString"}],"post":{"operationId":"DeleteAllDomainMessages","tags":["Messages"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"Delete all messages in a domain","description":"Delete all messages for a specifc domain. Starred messages will be deleted.\n\nThe domain must be owned domain.\n","responses":{"204":{"description":"All non-starred messages deleted"},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/me":{"get":{"operationId":"User","tags":["Account"],"summary":"Get current account","description":"Get information about the account for this API key.","security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"responses":{"200":{"$ref":"#/components/responses/CurrentUserInfo"},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/me/stats":{"get":{"operationId":"AccountStats","tags":["Account"],"summary":"Get account stats","description":"Get summary information about email addresses, domains, and usage.","parameters":[{"name":"overrideAccountId","in":"query","required":false,"schema":{"type":"string"}}],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"responses":{"200":{"$ref":"#/components/responses/CurrentUserStats"},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/addresses/{email}/messages/{messageId}/attachments":{"parameters":[{"$ref":"#/components/parameters/EmailString"},{"$ref":"#/components/parameters/messageId"}],"get":{"operationId":"ListMessageAttachments","tags":["Attachments"],"summary":"List attachments for an email message","description":"Get attachment metadata on email message.","security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"responses":{"200":{"$ref":"#/components/responses/AttachmentMeta"},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/addresses/{email}/messages/{messageId}/attachments/{attachmentIdentifier}":{"parameters":[{"$ref":"#/components/parameters/EmailString"},{"$ref":"#/components/parameters/messageId"},{"$ref":"#/components/parameters/attachmentIdentifier"}],"get":{"operationId":"DownloadAttachment","tags":["Attachments"],"summary":"Download email attachment","description":"Download an email message attachment as a file.","security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"responses":{"200":{"description":"OK","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/mailstats/common-attachments":{"parameters":[{"name":"startDate","in":"query","required":true,"schema":{"$ref":"#/components/schemas/Date"}},{"name":"endDate","in":"query","required":true,"schema":{"$ref":"#/components/schemas/Date"}},{"$ref":"#/components/parameters/skip"},{"$ref":"#/components/parameters/limit"}],"get":{"operationId":"ListPublicAttachments","tags":["Attachments"],"summary":"Search for attachments","description":"Search for attachments that were received during the requested time period. Limited to public\ninboxes and messages not starred by a user.\n\nResponds with 'Failed to fetch' in swagger editor. Works in curl with generated example.\n","security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/commonAttachments"}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/mailstats/common-attachments/{md5sum}/count":{"parameters":[{"$ref":"#/components/parameters/md5sum"}],"get":{"operationId":"CountPublicAttachments","summary":"Count public attachments","description":"Provides count of attachments by md5 sum\n\nResponds with 'Failed to fetch' in swagger editor, works in curl with generated example\n","tags":["Attachments"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"n":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/mailstats/common-attachments/{md5sum}":{"parameters":[{"$ref":"#/components/parameters/md5sum"}],"get":{"operationId":"ListMessagesForAttachment","summary":"List public messages with an attachment","description":"List the email messages that have attachments with the requested MD5 sum. Limited to non-private inboxes.","tags":["Attachments"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMessage"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/mailstats/common-attachments/{md5sum}/download":{"parameters":[{"$ref":"#/components/parameters/md5sum"}],"get":{"operationId":"DownloadPublicAttachment","summary":"Download public attachment","description":"Download an attachment with the MD5 sum requested.","tags":["Attachments"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/mailstats/top-addresses":{"parameters":[{"name":"startDate","in":"query","schema":{"$ref":"#/components/schemas/Date"}},{"name":"endDate","in":"query","schema":{"$ref":"#/components/schemas/Date"}},{"$ref":"#/components/parameters/skip"},{"$ref":"#/components/parameters/limit"}],"get":{"operationId":"ListTopPublicAddresses","tags":["messageStats"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"List top public disposable email addresses receiving messages","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"$ref":"#/components/schemas/EmailString"},"n":{"description":"count of messages","type":"integer"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/mailstats/top-senders":{"parameters":[{"name":"startDate","in":"query","schema":{"$ref":"#/components/schemas/Date"}},{"name":"endDate","in":"query","schema":{"$ref":"#/components/schemas/Date"}},{"$ref":"#/components/parameters/skip"},{"$ref":"#/components/parameters/limit"}],"get":{"operationId":"ListTopPublicSenders","tags":["messageStats"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"List top sender email addresses for disposable public messages","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"$ref":"#/components/schemas/EmailString"},"n":{"description":"count of messages","type":"integer"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/mailstats/top-domains":{"parameters":[{"name":"startDate","in":"query","schema":{"$ref":"#/components/schemas/Date"}},{"name":"endDate","in":"query","schema":{"$ref":"#/components/schemas/Date"}},{"$ref":"#/components/parameters/skip"},{"$ref":"#/components/parameters/limit"}],"get":{"operationId":"ListTopPublicDomains","tags":["messageStats"],"security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"summary":"List top public domains receiving disposable messages","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"description":"domain other than mailsac.com","type":"string","format":"domain"},"n":{"description":"count of messages","type":"integer"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/mailstats/blacklist":{"get":{"operationId":"Denylist","tags":["messageStats"],"summary":"List the current deny-list","security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/mailstats/blacklist/{domainOrIP}":{"parameters":[{"name":"domainOrIP","in":"path","required":true,"example":"gmail.com","schema":{"type":"string"}}],"get":{"operationId":"CheckDenylist","tags":["messageStats"],"summary":"Check IP or domain on deny-list","description":"Check whether an IP or domain is currently on the deny-list.","security":[{"APIKeyQueryParam":[]},{"APIKeyHeader":[]}],"responses":{"200":{"description":"Single property indicating deny-list status","content":{"application/json":{"schema":{"type":"object","properties":{"blacklisted":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}},"/custom_web_sockets":{"parameters":[{"name":"key","in":"query","schema":{"type":"string"},"description":"Mailsac-Key in the `?key=` querystring"},{"name":"addresses","in":"query","schema":{"type":"string"},"description":"Enhanced addresses or domains which are enabled for web socket messages","example":"[email protected],mail.mydomain.com"}],"post":{"operationId":"_doNotUse_WebSocketDocsOnly","tags":["Web Sockets"],"summary":"Connect a web socket to wss://sock.mailsac.com/incoming-messages","description":"*Note: this does not work in Swagger UI. Visit https://sock.mailsac.com to test.*\n\nYou can receive email via web socket for private email addresses and custom domains.\n\nTo enable web socket forwarding:\n\n* Addresses: Select *Edit* for the email address you want to forward.\nThen check the checkbox for web socket forwarding, and save.\n* Custom Domains: Select *Manage* for the domain and click the *Forwarding* tab. Toggle\nthe *Enable Web Sockets* option.\n\nNote: Web socket forwarding is **not enabled by default.**\n\n### Web Socket Examples\n\n#### Web Socket Test Page\n\nhttps://sock.mailsac.com\n\nReceive emails in your web browser.\n\nExperiment with the web socket gateway in realtime.\n\n#### Web Socket Node.js\n\nListen for Mailsac emails via websocket in this tiny Node.js example app.\n\nhttps://github.com/ruffrey/mailsac-node-websocket-example\n\n### Web Socket Connection Endpoint\n\nThe web socket endpoint is `wss://sock.mailsac.com/incoming-messages`\n\nExample:\n\n> wss://sock.mailsac.com/incoming-messages?key=k_e9bPnd2adexample&[email protected],asdf-outbound.mailsac.com\n\n> First frame:\n\n```\n{\n \"status\": 200,\n \"msg\": \"Listening\",\n \"addresses\": [\n \"[email protected]\"\n ],\n \"domains\": [\n \"asdf-outbound.mailsac.com\"\n ]\n}\n```\n\nAll web socket messages are JSON. After parsing the JSON, there will be a status field with\nan HTTP status code (usually 200).\n\nAn email coming over the web socket will also have an email property, and its value will be\nthe same as the messages REST API, plus some additional fields.\n","responses":{"101":{"description":"Successful web socket upgrade","content":{"application/json":{"example":{"type":"object","properties":{"status":{"type":"integer","example":200},"msg":{"type":"string","example":"listening"},"addresses":{"type":"array","items":{"type":"string","format":"email","example":"[email protected]"}},"domains":{"type":"array","items":{"type":"string","format":"email","example":"asdf-outbound.mailsac.com"}}}}}}}},"callbacks":{"emailMessageFrame":{"wss://sock.mailsac.com/incoming-messages":{"post":{"description":"Email message object received by your server","responses":{"101":{"description":"Web socket duplex response from your server"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMessageWebSocketFrame"}}}}}}}}}},"/custom_webhooks":{"post":{"operationId":"_doNotUse_WebhookDocsOnly","tags":["Webhooks"],"summary":"Receive a webhook email message on your server","description":"*Note: this does not work in Swagger UI.*\n\nWebhook Forwarding is one of several options available for enhanced addresses\nand custom domains (via catch-all addresses enabled under a custom domain).\n\nForwarding to a Webhook can be configured by selecting Manage Email Addresses from the\nDashboard. Select the Settings button next to the email address to manage, then input the\nURL under Forward To Custom Webhook and select Save Settings.\n\nTroubleshoot webhooks using your account *Audit Logs*.\n","responses":{"200":{"description":"No responses - webhooks are configured under enhanced addresses."}},"callbacks":{"emailMessageWebhook":{"https://your-server.com/endpoint":{"post":{"description":"Email message object received by your server","responses":{"200":{"description":"Expected response from your server is 200 status code"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMessageWebhook"}}}}}}}}}}},"components":{"securitySchemes":{"APIKeyQueryParam":{"type":"apiKey","name":"_mailsacKey","in":"query"},"APIKeyHeader":{"type":"apiKey","name":"Mailsac-Key","in":"header"}},"responses":{"UnauthorizedError":{"description":"Not authorized. You may need to log in first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseBody"}}}},"MessageNotFound":{"description":"Message not found by id...","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseBody"}}}},"OwnedByAnotherUser":{"description":"Requested email address is owned by another user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseBody"}}}},"AttachmentMeta":{"description":"Attachment Metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentMeta"}}}},"CurrentUserStats":{"description":"Current User Stats","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentUserStats"}}}},"CurrentUserInfo":{"description":"Current User Information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentUserInfo"}}}},"MessageHeaders":{"description":"Message Headers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageHeaders"}},"text/plain":{"example":"Received: \"\"\nReceived: \"\"\nX-Mailsac-Whitelist: \"\"\nDKIM-Signature: \"\"\nContent-Type: \"\"\nReceived: \"\"\nReceived: \"\"\nFrom: \"\"\nTo: \"\"\nSubject: \"\"\nMessage-ID: \"\"\nList-Unsubscribe: \"\"\nDate: \"\"\nMIME-Version: \"\"\n","schema":{"type":"string"}}}},"EmailAddressAvailability":{"description":"Object indicating if address is private or not","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailAddressAvailability"}}}}},"parameters":{"DomainString":{"in":"path","name":"domain","description":"Domain","required":true,"schema":{"$ref":"#/components/schemas/DomainString"}},"EmailString":{"in":"path","name":"email","description":"Email address","required":true,"schema":{"$ref":"#/components/schemas/EmailString"}},"DeleteAddressMessagesFlag":{"in":"query","name":"deleteAddressMessages","required":false,"schema":{"type":"boolean"}},"EmailStringList":{"in":"header","name":"emails","description":"email addresses","schema":{"$ref":"#/components/schemas/EmailStringList"}},"messageId":{"in":"path","name":"messageId","description":"Mailsac-generated globally unique message identifier","required":true,"schema":{"$ref":"#/components/schemas/MessageId"}},"Since":{"in":"query","name":"since","description":"Return messages returned after this UTC date","required":false,"schema":{"$ref":"#/components/schemas/Date"}},"Until":{"in":"query","name":"until","description":"Return messages returned up to this UTC date","required":false,"schema":{"$ref":"#/components/schemas/Date"}},"Label":{"in":"path","name":"label","description":"Label for email message - must be url encoded","example":"business%20archive","required":true,"schema":{"$ref":"#/components/schemas/MessageLabel"}},"MessageFolder":{"in":"path","name":"folder","description":"Folder for email organization","required":true,"schema":{"$ref":"#/components/schemas/MessageFolder"}},"readBoolean":{"description":"Set message read/unread","in":"path","name":"readBoolean","required":true,"schema":{"$ref":"#/components/schemas/readBoolean"}},"BrowserDownload":{"description":"Download to browser","in":"query","name":"download","required":false,"schema":{"type":"integer","enum":[1]}},"attachmentIdentifier":{"description":"Unique identifier of email attachment","in":"path","name":"attachmentIdentifier","required":true,"schema":{"$ref":"#/components/schemas/attachmentIdentifier"}},"md5sum":{"description":"md5 sum of an attachment","in":"path","name":"md5sum","required":true,"schema":{"$ref":"#/components/schemas/md5sum"}},"skip":{"in":"query","name":"skip","required":false,"schema":{"$ref":"#/components/schemas/skip"}},"limit":{"in":"query","name":"limit","required":false,"schema":{"$ref":"#/components/schemas/limit"}}},"schemas":{"ErrorResponseBody":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"validationErrors":{"type":"array","items":{"type":"string"}}}},"NotEnoughCreditsResponse":{"type":"object","properties":{"message":{"type":"string","example":"You must purchase more outgoing messages before you can send"}}},"TooManyRecipientsResponse":{"type":"object","properties":{"message":{"type":"string","example":"The to field exceeds the maximum allowed size"}}},"DomainString":{"type":"string","description":"domain","example":"example.msdc.co"},"EmailString":{"type":"string","format":"email","description":"email address","example":"[email protected]"},"EmailStringList":{"format":"array","description":"email addresses","items":{"$ref":"#/components/schemas/EmailString"},"example":["[email protected]","[email protected]"]},"EmailAddress":{"type":"object","properties":{"_id":{"type":"string","format":"email","description":"the unique identifier of this email address is the email address itself"},"info":{"type":"string","description":"Allows setting custom information about this email address."},"enabledws":{"type":"boolean","description":"boolean defaulting false indicating whether to publish messages via web socket when the user owning this inbox is subscribed"},"forward":{"type":"string","format":"email","description":"email address where messages to this inbox will be forwarded"},"webhook":{"type":"string","format":"url","description":"URL where messages to this inbox will be forwarded"},"webhookSlack":{"type":"string","format":"url","description":"Slack webhook endpoint where messages should be published"},"webhookSlackToFrom":{"type":"boolean","description":"When webhookSlack is set, controls whether the message includes TO and FROM"},"owner":{"type":"string","description":"Account that owns the address (owns the privacy)"},"encryptedInbox":{"type":"string","format":"email","example":"[email protected]","description":"An alternate email address that will result in the message being delivered to this inbox. This is not always present."},"catchAll":{"type":"string","format":"domain","description":"Indicates whether this is a catch-all address, and for which domain."},"implicit":{"type":"boolean","default":false,"description":"When the user owns the domain but has not reserved the address individually, this field is set to true."},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"}}},"EmailAddressList":{"format":"array","description":"email addresses","items":{"$ref":"#/components/schemas/EmailAddress"}},"EmailMessage":{"type":"object","properties":{"_id":{"$ref":"#/components/schemas/MessageId"},"from":{"type":"array","description":"The FROM sender, this will always have 1 item in the array unless the email was malformed.","items":{"$ref":"#/components/schemas/EmailRecipient"}},"to":{"type":"array","description":"The RCPT-TO recipients of the email.","items":{"$ref":"#/components/schemas/EmailRecipient"}},"cc":{"type":"array","description":"CarbonCopy recipients of the email.","items":{"$ref":"#/components/schemas/EmailRecipient"}},"bcc":{"type":"array","description":"BlindCarbonCopy recipients of the email.","items":{"$ref":"#/components/schemas/EmailRecipient"}},"subject":{"$ref":"#/components/schemas/EmailSubject"},"savedBy":{"type":"string","description":"Indicates a starred message by your account Account._id. Otherwise `null`."},"originalInbox":{"type":"string","description":"Same as inbox unless sent to the encryptedInbox, in which case it would be the encryptedInbox."},"inbox":{"type":"string","description":"Email address to which this message belongs.","format":"email"},"domain":{"type":"string","format":"domain","example":"example.com","description":"hostname domain for the inbox"},"received":{"$ref":"#/components/schemas/Date"},"size":{"type":"number","description":"Content length in bytes of the original raw email message"},"attachments":{"type":"array","description":"`null` or array of MD5 hashes of attachments. Use the Attachments API to get metadata and download attachments.","items":{"$ref":"#/components/schemas/md5sum"}},"ip":{"type":"string","description":"The remote SMTP server that send the mail to the server at `via`"},"via":{"type":"string","description":"IP address of SMTP server that received the message from `ip`"},"folder":{"type":"string","description":"Inbox folder that this message has been put into","default":"inbox","enum":["inbox","all","spam","trash"]},"labels":{"type":"array","items":{"type":"string"},"description":"Custom inbox labels created by the end user"},"read":{"type":"boolean","description":"Read/uread status. true=read, false=unread. Only set from the Inbox UI app."},"rtls":{"type":"boolean","description":"When true, indicates the SMTP message was received over TLS (encrypted)."},"links":{"type":"array","items":{"type":"string"},"description":"List of any URLs that were found in the text and HTML body of the message."},"spam":{"type":"number","example":0.345,"description":"Experimental - result of spam filter scan, between 0.0 and 1.0, where 1.0 indicates a high likelihood of being spam"}}},"EmailMessageBodyProps":{"type":"object","properties":{"text":{"type":"string","description":"Plain text email body"},"body":{"type":"string","description":"HTML email body"},"raw":{"type":"string","description":"Entire SMTP original message including headers and attachments"},"headers":{"type":"object","description":"Key-value pairs of headers where the value is an array of strings"}}},"EmailMessageWebSocketFrame":{"description":"Entire email message plus parsed body and raw SMTP","type":"object","properties":{"status":{"type":"integer","example":200},"email":{"allOf":[{"$ref":"#/components/schemas/EmailMessageBodyProps"},{"$ref":"#/components/schemas/EmailMessage"}]}}},"EmailMessageWebhook":{"allOf":[{"$ref":"#/components/schemas/EmailMessageBodyProps"},{"$ref":"#/components/schemas/EmailMessage"}]},"EmailMessageList":{"type":"array","description":"List of full email message objects","items":{"$ref":"#/components/schemas/EmailMessage"}},"EmailMessageListShort":{"type":"array","description":"List of condensed email message objects","items":{"$ref":"#/components/schemas/EmailMessageShort"}},"EmailMessageShort":{"type":"object","properties":{"inbox":{"$ref":"#/components/schemas/EmailMessage/properties/inbox"},"to":{"$ref":"#/components/schemas/EmailMessage/properties/to"},"from":{"$ref":"#/components/schemas/EmailMessage/properties/from"},"subject":{"$ref":"#/components/schemas/EmailMessage/properties/subject"},"originalInbox":{"$ref":"#/components/schemas/EmailMessage/properties/originalInbox"},"size":{"$ref":"#/components/schemas/EmailMessage/properties/size"},"attachments":{"$ref":"#/components/schemas/EmailMessage/properties/attachments"},"received":{"$ref":"#/components/schemas/EmailMessage/properties/received"},"bcc":{"$ref":"#/components/schemas/EmailMessage/properties/bcc"},"cc":{"$ref":"#/components/schemas/EmailMessage/properties/cc"},"domain":{"$ref":"#/components/schemas/EmailMessage/properties/domain"},"folder":{"$ref":"#/components/schemas/EmailMessage/properties/folder"},"ip":{"$ref":"#/components/schemas/EmailMessage/properties/ip"},"labels":{"$ref":"#/components/schemas/EmailMessage/properties/labels"},"links":{"$ref":"#/components/schemas/EmailMessage/properties/links"},"read":{"$ref":"#/components/schemas/EmailMessage/properties/read"},"rtls":{"$ref":"#/components/schemas/EmailMessage/properties/rtls"},"savedBy":{"$ref":"#/components/schemas/EmailMessage/properties/savedBy"},"spam":{"$ref":"#/components/schemas/EmailMessage/properties/spam"},"via":{"$ref":"#/components/schemas/EmailMessage/properties/via"}}},"DomainsList":{"type":"array","description":"List of custom domain objects","items":{"$ref":"#/components/schemas/Domain"}},"Domain":{"type":"object","description":"Custom domain","properties":{"_id":{"type":"string","format":"domain","description":"domain"},"created":{"type":"string","format":"date-time","description":"Date domain was created"},"updated":{"type":"string","format":"date-time","description":"Date domain settings were last updated"},"enablews":{"type":"boolean","description":"boolean defaulting false indicating whether to publish messages via\nweb socket to any subscribed web socket sessions\n"},"hosted":{"type":"boolean","description":"boolean defaulting false indicating whether this is managed by mailsac (on msdc.co)"},"isDefault":{"type":"boolean","description":"boolean defaulting false indicating whether this is the default\ndomain for the account which will show in the sidebar first\n"},"isPrivate":{"type":"boolean","description":"boolean defaulting true indicating whether inboxes and messages for this domain will be visible publicly\n"},"lastVerificationErrors":{"type":"string","description":"during custom domain verification, this field indicates dns issues"},"owner":{"type":"string","description":"the account to which this domain is assigned and can be managed"},"verificationTxt":{"type":"string","description":"during custom domain verification, this field indicates value of a TXT record that must be added to the domain's DNS settings\n"},"verified":{"type":"boolean","description":"boolean defaulting false indicating whether this domain has been verified via dns TXT record verificationTxt\n"},"verifiedMx":{"type":"boolean","description":"boolean defaulting false indicating whether the domain will receive email successfully at Mailsac. Tthis domain has been verified via dns MX records when true.\n"}}},"EmailRecipient":{"type":"object","properties":{"name":{"type":"string","description":"friendly email name, optional part of transport so may be empty string"},"address":{"type":"string","description":"email address"}}},"UpdatePrivateAddressForwarding":{"description":"body object to update address forwarding","properties":{"info":{"type":"string","description":"User configurable metadata about this enhanced private address."},"forward":{"type":"string","description":"email address - SMTP forwarding / standard email forwarding - set to \"\" or null to disable forwarding","default":""},"enablews":{"type":"boolean","description":"boolean, defaults false - set to true to enable web socket forwarding (see Web Socket API)","default":false},"webhook":{"description":"url - set to your public webhook endpoint to receive mail via webhook - set to \"\" or null to disable webhooks","type":"string","default":""},"webhookSlack":{"description":"Slack webhook URL where messages will be published.","type":"string","default":""},"webhookSlackToFrom":{"type":"boolean","description":"When webhookSlack is set, controls whether the message includes TO and FROM"}}},"EmailAddressIntegrity":{"type":"object","required":["email","validFormat"],"properties":{"email":{"type":"string","format":"email","example":"[email protected]","description":"Full email address that was checked."},"validFormat":{"type":"boolean","description":"Indicates if the format is valid."},"local":{"type":"string","example":"billy.wilson","description":"The \"local part\" of the email address, before the @ symbol."},"domain":{"type":"string","format":"domain","example":"example.com","description":"The domain of the email address which was used for evaluating disposable components, after the @ symbol."},"isDisposable":{"type":"boolean","description":"Boolean indicating if this email address is known to resolve to disposable email providers, most likely making it not useful for marketing mailing lists or signups."},"disposableDomains":{"type":"array","format":"domain","example":["example.com","others.org"],"items":{"type":"string"},"description":"Array of string domains where this email resolves to, which is helpful when the domain is custom, but receives its mail at a disposable email provider."},"aliases":{"type":"array","example":["example.com","192.168.0.1","example.io"],"items":{"type":"string","format":"domain"},"description":"Array of string domains and IP addresses which are associated with the domain for this email address."}}},"EmailSubject":{"type":"string","description":"Email subject header line. Can be an empty string."},"EmailAddressIntegrityList":{"type":"array","items":{"$ref":"#/components/schemas/EmailAddressIntegrity"}},"EmailAddressAvailability":{"type":"object","description":"Returns object showing email address availability","properties":{"available":{"type":"boolean","description":"Indicates if the address is available to be reserved"},"email":{"type":"string","format":"email","description":"email address"},"owned":{"type":"boolean","description":"Indicates if the address is owned by an account, but not by whom."}}},"MessageId":{"type":"string","format":"string","description":"Unique Mailsac-generated identifier for an email message","example":"m3phnJ2ag3example-0"},"Date":{"type":"string","description":"Date in ISO 8601","format":"date","example":"1985-04-12T23:20:50.52Z"},"MessageLabel":{"type":"string","description":"Label for email message"},"MessageLabels":{"type":"array","description":"Labels for an email message","items":{"$ref":"#/components/schemas/MessageLabel"}},"MessageFolder":{"type":"string","description":"Folders for a email messages","enum":["inbox","all","spam","trash"]},"readBoolean":{"type":"boolean","description":"True to mark message as read, False to mark message unread. Default False"},"MessageHeaders":{"oneOf":[{"type":"object","description":"SMTP headers are returned as json with header values grouped.","example":{"dkim-signature":[""],"received":["",""],"date":[""]},"additionalProperties":{"type":"array","items":{"type":"string"}}},{"type":"object","description":"SMTP headers are returned as JSON maintaining their original order.","example":[{"name":"dkim-signature","value":""},{"name":"received","value":""},{"name":"received","value":""}],"additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string"}}}}]},"EmailAttachment":{"type":"object","description":"Email attachment object","properties":{"cid":{"type":"string","description":"contentid"},"contentDisposition":{"type":"string"},"encoding":{"$ref":"#/components/schemas/ByteEncoding"},"filename":{"type":"string"}}},"EmailAttachmentList":{"type":"array","description":"Array of Email Attachment Objects","items":{"$ref":"#/components/schemas/EmailAttachment"}},"ByteEncoding":{"type":"string","enum":["byte","base64"]},"SendMessage":{"type":"object","description":"JSON formatted email message used for sending","properties":{"to":{"$ref":"#/components/schemas/SendMessageTo"},"from":{"$ref":"#/components/schemas/SendMessageFrom"},"subject":{"$ref":"#/components/schemas/EmailSubject"},"text":{"type":"string","description":"plaintext email contents"},"html":{"type":"string","description":"html email contents"},"attachments":{"$ref":"#/components/schemas/EmailAttachmentList"},"received":{"type":"array","items":{"$ref":"#/components/schemas/ReceivedHeadersList"}},"raw":{"description":"raw SMTP messsage overrides all other properties","type":"string"}},"required":["to","from","subject","text","html"]},"ReceivedHeaders":{"type":"string","description":"SMTP Received headers"},"ReceivedHeadersList":{"type":"array","description":"Array of strings of current and possibly previous received headers","items":{"$ref":"#/components/schemas/ReceivedHeaders"}},"SendMessageTo":{"description":"To addresses for SendMessage Object","oneOf":[{"$ref":"#/components/schemas/EmailString"},{"$ref":"#/components/schemas/EmailStringList"}]},"SendMessageFrom":{"description":"To addresses for SendMessage Object","oneOf":[{"$ref":"#/components/schemas/EmailString"},{"$ref":"#/components/schemas/EmailStringList"}]},"CurrentUserInfo":{"description":"Information regarding the current user","type":"object","properties":{"_id":{"type":"string","description":"username","example":"my_username"},"email":{"$ref":"#/components/schemas/EmailString"},"invoiceEmail":{"$ref":"#/components/schemas/EmailString"},"capturePrivate":{"type":"boolean","description":"Setting which will apply a star to all captured emails."},"messageLimit":{"type":"integer","description":"Maximum allowed message history (starred messages + all messages on enhanced addresses and domains)","example":1000},"privateDomain":{"type":"integer","description":"Number of custom domain that the account is entitled to but has not yet reserved"},"privateAddressCredits":{"type":"integer","description":"Number of enhanced addresses that the account is entitled to but has not yet reserved","example":100},"whitelistAccess":{"type":"integer","description":"Flag indicating whether account is allowed to request adding IPs to the global allow-list.","enum":[0,1]},"moAPICount":{"type":"integer","description":"Approximate number of total API calls made by the account this month"},"apiMonthlyLimit":{"type":"integer","description":"Number of API calls allowed monthly"},"billingHold":{"type":"string","description":"When present, indicates the account has past-due invoices and service is disabled"},"disabled":{"type":"string","description":"When present, indicates a disabled account"},"recents":{"type":"array","description":"The most recent email addresses viewed by this account in the UI","items":{"$ref":"#/components/schemas/EmailString"}},"labels":{"description":"Inbox labels created by the account","type":"array","items":{"type":"string"}},"company":{"type":"string","description":"Company name associated with account"},"address":{"type":"string","description":"Company address associated with account"},"firehose":{"type":"integer","description":"Entitlement flag indicating whether the account has access to the Firehose Web Socket API"},"allowPublicDomains":{"type":"integer","description":"Entitlement flag indicating whether the account has access to Public Domains","enum":[0,1]},"viewAnalytics":{"type":"integer","description":"Flag indicating whether account is allowed to view analytics","enum":[0,1]},"apiAccess":{"type":"integer","description":"Flag indicating whether account has access to API","enum":[0,1]},"wsDomain":{"type":"integer","enum":[0,1]},"manyKeys":{"type":"integer","enum":[0,1]},"internalUnlimited":{"type":"integer","enum":[0,1]},"lastLogin":{"$ref":"#/components/schemas/Date"},"allowMultipleUsers":{"type":"integer","enum":[0,1]},"userLimit":{"type":"integer","description":"Number of users "},"stripeId":{"type":"string"},"moAPIDisabled":{"type":"integer"},"moAPILimitWarningEmail":{"type":"integer"},"apiKeyName":{"type":"string"}}},"CurrentUserStats":{"description":"Describes current user stats","type":"object","properties":{"addresses":{"description":"List of owned email addresses","type":"array","items":{"$ref":"#/components/schemas/EmailString"}},"domains":{"type":"array","description":"List of custom domains","items":{"type":"string","format":"domain"}},"starredMessages":{"type":"integer","minimum":0,"example":100,"description":"Total count of saved messages"},"storedMessages":{"type":"integer","minimum":0,"example":100,"description":"Total messages on all enhanced addresses and custom domains"},"inboxBytes":{"type":"integer","minimum":0,"example":1024,"description":"Sum size of all messages on enhanced addresses and custom domains"},"lastMonthOps":{"type":"integer","description":"Count of paid ops performed in the previous month"},"defaultDomain":{"type":"string","description":"Domain set to default"}}},"AttachmentMeta":{"description":"Describes metadata for attachment","type":"object","properties":{"checksum":{"$ref":"#/components/schemas/md5sum"},"contentDisposition":{"type":"string","description":"TODO: describe"},"contentId":{"$ref":"#/components/schemas/attachmentIdentifier"},"contentType":{"type":"string","description":"Content type of the attachment","example":"application/PDF"},"fileName":{"type":"string","description":"Filename of attachment","example":"w2.pdf"},"length":{"type":"integer","minimum":0,"description":"length of attachment","example":42532},"transferEncoding":{"type":"string","description":"Encoding used for attachment","example":"base64"}}},"attachmentIdentifier":{"description":"Unique identifier for message attachment. Can be the md5sum, smtp content-id (cid), or filename.","type":"string","example":"5ea9c924627e68f988c9c7ca44340892 || foo4*[email protected] || horse.png"},"commonAttachments":{"description":"Common attachments received","type":"object","properties":{"_id":{"$ref":"#/components/schemas/md5sum"},"n":{"type":"integer","description":"Count of public messages with this attachment"}}},"md5sum":{"description":"md5 checksum on attachment file","type":"string","example":"5ea9c924627e68f988c9c7ca44340892","format":"md5sum"},"skip":{"description":"How many items to skip (like paging)","type":"integer","minimum":0,"default":0},"limit":{"description":"Limit results to this many","type":"integer","minimum":0,"default":20,"maximum":1000}}}}