Check Mail

Now that curl and jq are installed, we can start interacting with Mailsac API. The Mailsac API Reference includes all supported endpoints. The API Reference is great starting place, if you a familiar with REST APIs, or for reference after completing this step-by-step introduction.

In this example, we are going to check an arbitrary email address for mail, read that email and respond to the email.

We will list inbox email messages for To list the available messages we will use the List Inbox Email Messages endpoint.


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

This endpoint can be accessed with GET /api/addresses/:email/messages. You will substitute :email with giving us GET /api/addresses/ Curl does not encode URLs. The @ character needs to be URL encoded as %40. GET /api/addresses/ The base URI of the Mailsac API is, which translates to


You can validate the url is properly formatted by accessing it in your web browser. Go ahead and try it with our example or try it with a different email address.

Curl requires us to add a few extra parameters. -X GET instructs curl to us a HTTP GET request. -s suppresses a progress bar. In the command below we pipe the contents of curl into JQ for JSON formatting. JQ requires a filter to function. We are using the simplest filter “.” which matches all JSON. user1@mailsac is a popular address and receives lots of email. JQ will only show the first JSON object with the filter “.[0]”

Retrieve first email in a an inbox.
$ curl -s -X GET | jq ".[0]"
Inbox message
  "_id": "BotvTxaona7gLID1Adtpfj8Fnfi7HSSv-0",
  "from": [
      "address": "[email protected]",
      "name": "Microsoft Store"
  "to": [
      "address": "[email protected]",
      "name": ""
  "cc": null,
  "bcc": null,
  "subject": "Ahoy, Sea of Thieves for PC is here",
  "savedBy": null,
  "originalInbox": "[email protected]",
  "inbox": "[email protected]",
  "domain": "",
  "received": "2018-03-29T18:28:07.732Z",
  "size": 23420,
  "attachments": null,
  "ip": "",
  "via": "",
  "folder": "inbox",
  "labels": [],
  "read": null,
  "rtls": true,
  "links": [
  "spam": 1.3370381090039505e-09

As you can see, the JSON contains information about the email message including to address, from address, subject, time stamp, attachments and much more. Make note of the _id field, you will use it to view the contents of the email.