{{ notif.message || notif.error || notif }}
{{ qs.message }}
{{ qs.error }}

Developer APIs

Paid accounts  can generate an API key token to assist with automation. Learn more

Contact us for advanced querying and mail stats.


API keys are 64 character alphanumeric cryptographically random tokens.

Go to the API Keys section on the Dashboard to manage your account's API keys.


You can use POP3 to fetch messages for an owned address from any email client. Instructions for POP3 →

Web Socket API


You can receive email via web socket, for your private email addresses.

To enable web socket forwarding, select "Edit" for the email address you want to forward. Then check the checkbox for web socket forwarding, and save. Web socket forwarding is not enabled by default.


Web Socket Test Page


Receive emails in your web browser.

Experiment with the web socket gateway in realtime.

Node.js Example


Listen for Mailsac emails via websocket in this tiny Node.js example app.


Web Socket Connection Endpoint

The web socket endpoint is wss://sock.mailsac.com/incoming-messages.

The following query string params are required:

  • _id - your account username (aka _id).
  • key - your account's API key.
  • addresses - a comma separated list of addresses you wish to listen for messages on. These must be private addresses that your account owns.
Example Web Socket Connection URL

Web Socket Message Format

All web socket messages are JSON. After parsing the JSON, there will be a status field with an HTTP status code (usually 200).

An email coming over the web socket will also have an email property, and its value will be the same as the messages REST API, plus some additional fields:

Example Web Socket Frame
  "status": 200,
  "email": {
    "_id": "W0YIhkgWJxcZc1qujq2w6f1YPZwFc",
    "from": [
        "name": "",
        "address": "foo@mailsac.com"
    "to": [
        "name": "",
        "address": "bar@mailsac.com"
    "subject": "Hi hello",
    "originalInbox": "bar@mailsac.com",
    "inbox": "bar@mailsac.com",
    "domain": "mailsac.com",
    "received": "2017-05-01T01:39:27.940Z",
    "body": "
", "html": "
", "raw": "DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=mailsac.com;\r\n q=dns/txt; s=mailsacrelay;\r\n h=from:subject:to:mime-version:content-type:content-transfer-encoding:list-unsubscribe;\r\n b=redacted\r\nReceived: from localhost ( by fortune with SMTP; Sun Apr 30\r\n 2017 21:40:10 GMT-0400 (EDT)\r\nContent-Type: text/plain\r\nFrom: foo@mailsac.com\r\nTo: bar@mailsac.com\r\nSubject: Hi me\r\nMessage-ID:\r\n \r\nList-Unsubscribe: \r\nContent-Transfer-Encoding: 7bit\r\nDate: Mon, 01 May 2017 01:40:10 +0000\r\nMIME-Version: 1.0\r\n\r\nYoooo", "headers": { "content-transfer-encoding": "7bit", "content-type": "text/plain", "date": "Mon, 01 May 2017 01:40:10 +0000", "dkim-signature": "<redacted>", "from": "foo@mailsac.com", "list-unsubscribe": "", "message-id": "", "mime-version": "1.0", "received": "from localhost ( by fortune with SMTP; Sun Apr 30 2017 21:40:10 GMT-0400 (EDT)", "subject": "Hi me", "to": "bar@mailsac.com" }, "text": "Yoooo" } }

Email Object
    _id: "",
    from: [Recipient],
    to: [Recipient],
    subject: "hi",
    originalInbox: "test@example.com", // the same as inbox unless sent to the encryptedInbox
    inbox: "test@example.com",
    domain: "example.com",
    received: "2016-08-16T02:59:13.406Z",
    body: "<div>hey there</div>", // cleaned HTML body
    html: "<div>hey there</div>", // full unsafe HTML body
    raw: "", // full email transport text
    headers: {}, // parsed smtp headers with all key fields lowercased ("reply-to")
    text: "hey there" // the text representation of the email

Recipient Object
    name: "Bill Jones",
    address: "billjones@example.com"



There are 3 ways to authenticate to the REST API.

1. HTTP Header

Create an HTTP header for Mailsac-Key.

Mailsac-Key: eoj1mn7x5y61w0egs25j6xrvs6lwrrld0oh43rj583cgdps10tokp2ceux9s6ri8

2. Query string parameter

In the query section of the URL (after ?) add a parameter for _mailsacKey.


3. Request body

During a POST request, add a JSON field for _mailsacKey.

  "_mailsacKey": "eoj1mn7x5y61w0egs25j6xrvs6lwrrld0oh43rj583cgdps10tokp2ceux9s6ri8"

Address REST APIs

GET /api/addresses

Get an array of private inbox address objects for the account.

GET /api/addresses/:email

Get a single address object.

Returns an object if owned by the user or not owned.

Returns 401 if owned by other user.

Example Response
    _id: "somewhere@mailsac.com",
    created: "2013-02-05T15:10:33.234Z",
    enablews: true,
    forward: "somewhere@example.com",
    webhook: "https://example.com/email-callback",
    owner: "your account._id",
    encryptedInbox: "inbox-d6da59f7a6e78d9abba34c4"

GET /api/addresses/:email/availability

Check if an address is owned.

Example Response
    available: true,
    email: "ae638ef@mailsac.com",
    owned: false

POST /api/addresses/:email

Reserve ownership of a private email address.

No POST body is required.

Returns 200 if successfully reserves the address.

Returns 401 if owned by other user.

Returns 400 if it is already owned by the user.

DELETE /api/addresses/:email

Release ownership of a private address.

Returns 200 if successfully releases the address.

Returns 401 if owned by other user.

Returns 400 if it is not owned.

PUT /api/private-address-forwarding/:email

For a privately owned address :email, set it to forward to another email.

To receive a webhook notification of each email, set webhook to your webhook server endpoint.

To enable receiving emails via web socket (see Web Socket API above), set enablews to true. Leaveforward empty to disable forwarding.

Example PUT Body
    "forward": "newemail@example.com",
    "enablews": true,
    "webhook": "https://example.com/email-callback"

Email Message REST APIs

GET /api/addresses/:email/messages

Get the list of messages for an email inbox.

GET /api/addresses/starred/messages

Get the list of messages that have been saved and made private for the user.

GET /api/addresses/:email/messages/:messageId

Get detailed information about the message, including original headers.

DELETE /api/addresses/:email/messages/:messageId

Remove a message.

PUT /api/addresses/:email/messages/:messageId/star

Toggle starred status so it gets saved from autoremoval.

GET /api/headers/:email/:messageId

Optional querystring param?download=1 to trigger file download in browser.

Returns a JSON object with headers from the email.

Example Headers
     dkim-signature: "",
     received: "",
     x-facebook: "",
     date: "",
     to: "",
     subject: "",
     x-priority: "",
     x-mailer: "",
     return-path: "",
     from: "",
     reply-to: "",
     errors-to: "",
     x-facebook-notify: "",
     list-unsubscribe: "",
     x-facebook-priority: "",
     x-auto-response-suppress: "",
     require-recipient-valid-since: "",
     message-id: "",
     mime-version: "",
     content-type: ""

GET /api/body/:email/:messageId

Optional querystring param?download=1 to trigger file download in browser.

Sanitized HTML version of the original message.

GET /api/dirty/:email/:messageId

Optional querystring param?download=1 to trigger file download in browser.

Full unsanitized HTML from the original message.

GET /api/text/:email/:messageId

Optional querystring param?download=1 to trigger file download in browser.

Text representation of the email message.

GET /api/raw/:email/:messageId

Optional querystring param?download=1 to trigger file download in browser.

The entire original SMTP message transport message.

POST /api/outgoing-messages

Send an email message.

Example POST body
  "to": "someone@example.com",
  "from": "somebody@mailsac.com",
  "subject": "Hey",
  "text": "Message text body, no sending html allowed sorry."

User APIs

GET /api/me

Retrieve user account.

Example Response
    _id: "my_username",
    email: "outside-email@example.com",
    messageLimit: 1000,
    sendsRemaining: 362,
    catchAll: 0,
    privateAddressCredits: 1,
    recents: [
    noAds: 1

GET /api/me/stats

Get information about non-owned addresses with starred messages and total starred messages, and list of owned addresses.

Example Response
    storedMessages: 40,
    starredMessages: 14,
    addresses: [
    nonOwnedInboxes: [

POST /api/auth/logout

Destroy your session. For cookie auth only (website).