{{ 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 Key

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.

POP3

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

https://sock.mailsac.com

You can receive emails via web socket instantly on the web socket test page.

Node.js Example

https://github.com/ruffrey/mailsac-node-websocket-example

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 URL
wss://sock.mailsac.com/incoming-messages?_id=myusername;&key=skkie9bksd2ad&addresses=1@mailsac.com,2@mailsac.com

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:

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"
}

REST API


Authentication

There are 3 ways to authenticate to the 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.

https://mailsac.com/api/some-route?_mailsacKey=eoj1mn7x5y61w0egs25j6xrvs6lwrrld0oh43rj583cgdps10tokp2ceux9s6ri8

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",
    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 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
}

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,
    privateAddressCredits: 1,
    recents: [
        "example@mailsac.com",
        "mailsac@example.com"
    ],
    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: [
        "example@mailsac.com",
        "mailsac@example.com"
    ],
    nonOwnedInboxes: [
        "some-public-addr@mailsac.com"
    ]
}

POST /api/auth/logout

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