REST API - Getting Started

This example will show how to do the following using the REST API.

  • list emails sent to

  • read an email sent to can be replaced with any email address hosted by Mailsac. If you are familiar with REST APIs the REST API Specification can be referenced during this example.

REST API Overview

REST API interaction is at the core of Mailsac. The examples in this section will provide you with easy to understand curl examples. For additional code examples (Nodejs and Python) see: Reading Email.


API access is included with all Mailsac accounts. Create or view your API key. Your API key will be used as the value for the Mailsac-Key Authentication Header.

curl is the only program used in this example. If you are using Linux or OS X curl is likely already installed. The following commands can be used to install curl.

For operating systems using yum
sudo yum install curl -y
For operating system using apt
sudo apt-get install curl -y
For OS X
brew install curl
For Windows’s Operating System using Chocolately Nuget.
chocolately install curl


jq can be used to parse JSON, making the output from curl pretty.

Get Mail

To list the available messages for we will use the /api/addresses/:email/messages endpoint. This endpoint accepts one parameter :email. After substituting the :email parameter and providing the required Authentication Header, the following curl command will return JSON.

Retrieve list of messages in an inbox.
curl -H 'Mailsac-Key: YOUR_API_KEY_HERE'
Inbox messages
  "_id": "BotvTxaona7gLID1Adtpfj8Fnfi7HSSv-0",
  "from": [
      "address": "",
      "name": "Microsoft Store"
  "to": [
      "address": "",
      "name": ""
  "cc": null,
  "bcc": null,
  "subject": "Ahoy, Sea of Thieves for PC is here",
  "savedBy": null,
  "originalInbox": "",
  "inbox": "",
  "domain": "",
  "received": "2018-03-29T18:28:07.732Z",
  "size": 23420,
  "attachments": ["c830ee26e0a326e0a30c585494793479"],
  "ip": "",
  "via": "",
  "folder": "inbox",
  "labels": [],
  "read": null,
  "rtls": true,
  "links": [
  "spam": 0.331

The returned JSON contains metadata about the email message including to address, from address, subject, time stamp, attachments and much more. Make note of the _id field, it will be used it to view the contents of the email.


API documentation is generalized. Modifications are needed to translate an API endpoint into a usable URL. The base URI of all Mailsac API requests will be

Read Mail

To read an email message we will use the /api/text/:email/:messageId endpoint. This endpoint requires two parameters, :email and :messageId. After substituting the :email and :messageId parameters and providing the required Authentication Header, the following curl command will return a plain-text version of the message.

Retrieve text of message
curl -H "Mailsac-Key: YOUR_API_KEY_HERE"
Plain text email message
Enjoy odoo partnership program and success pack sales combo! *
Summer is around the corner! Odoo wishes  to save your time and effort from complicated paperwork for more outdoor activities!    Therefore, we are offering an exclusive discount for Partnership in MAY.
Partnership program pricing at USD 2950
*  and save USD 1000* on your joining!
*  *The discount offer is only applicable for the purchase with a success pack.

Schedule a demo with
Odoo Partnership Expert* BOOK NOW [2]
Our Partnership
Program*  READ MORE [3]
* Our Worldwide Partners*  READ MORE [4]
* Our Customers success story*  READ MORE [5]
None [6]  None [7]  None [8]  None [9]
Unsubscribe [10] | Contact [11]
2018 All Rights Reserved


The /text/ portion of the URL can be replaced with other values, to retrieve different parsed representations of the SMTP body.

  • /text/ plaintext email body, or HTML parsed to plaintext

  • /raw/ entire received SMTP message including headers, body, and attachments

  • /body/ HTML body, with images, links and scripts scrubbed

  • /dirty/ HTML body, with nothing scrubbed and images inlined

  • /headers/ JSON object representation of SMTP headers. The key will be the header key, lowercased. When there are multiple headers with the same name , such as Received header, the value of the header will be an array of strings. Otherwise the value will be a string.