REST API - Getting Started

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

list emails sent to user1@mailsac.com
read an email sent to user1@mailsac.com

user1@mailsac.com 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.

Prerequisites

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

Tip

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

Get Mail

To list the available messages for user1@mailsac.com 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' https://mailsac.com/api/addresses/user1@mailsac.com/messages

Inbox messages

[{
  "_id": "BotvTxaona7gLID1Adtpfj8Fnfi7HSSv-0",
  "from": [
    {
      "address": "microsoftstore@e.microsoft.com",
      "name": "Microsoft Store"
    }
  ],
  "to": [
    {
      "address": "user1@mailsac.com",
      "name": ""
    }
  ],
  "cc": null,
  "bcc": null,
  "subject": "Ahoy, Sea of Thieves for PC is here",
  "savedBy": null,
  "originalInbox": "inbox-c942bfeeafb96c0e5ce8b4e5c0d747c608@mailsac.com",
  "inbox": "user1@mailsac.com",
  "domain": "mailsac.com",
  "received": "2018-03-29T18:28:07.732Z",
  "size": 23420,
  "attachments": ["c830ee26e0a326e0a30c585494793479"],
  "ip": "65.55.234.211",
  "via": "144.202.71.79",
  "folder": "inbox",
  "labels": [],
  "read": null,
  "rtls": true,
  "links": [
    "https://support.xbox.com/games/game-titles/xbox-play-anywhere-help",
    "https://e.microsoft.com/Key-3567701.C.CQZpy.J.K0.-.CpMBp0",
    "https://account.microsoft.com/profile/unsubscribe?CTID=0&ECID=jIce0uXtDC5qRlyCYqZsz5yCL"
  ],
  "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.

Tip

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 https://mailsac.com.

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" https://mailsac.com/api/text/user1@mailsac.com/Jn1wa9AwLigQwIbwUGyMMollJkeWSeUd-0

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



[1] https://www.odoo.com/r/erT/m/12928017
[2] https://www.odoo.com/r/X6Q/m/12928017
[3] https://www.odoo.com/r/so8/m/12928017
[4] https://www.odoo.com/r/fya/m/12928017
[5] https://www.odoo.com/r/jlI/m/12928017
[6] https://www.odoo.com/r/dlt/m/12928017
[7] https://www.odoo.com/r/25S/m/12928017
[8] https://www.odoo.com/r/Vcu/m/12928017
[9] https://www.odoo.com/r/nKf/m/12928017
[10] https://www.odoo.com/unsubscribe_from_list
[11] https://www.odoo.com/r/rox/m/12928017

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.