Email and SMS Testing API

Using the Mailosaur API, you can write automated tests for the email and SMS messages your product sends.

Overview

The Mailosaur API lets you test email using a simple REST API. You can make the API calls yourself, however because email and SMS messages can take time to arrive, we highly recommend using one of our official clients.

Authentication

The Mailosaur API uses API keys to authenticate requests.

Authentication to the API is performed via HTTP Basic Auth. Your API key must be provided as the basic auth username value. You do not need to provide a password.

Your API keys carry many privileges, so always keep them secret and secure! Never share your API key in publicly-accessible areas such GitHub, client-side code, etc.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

curl https://mailosaur.com/api/servers \
  -u YOUR_API_KEY:

Managing API keys

You can manage all your API keys in the Mailosaur Dashboard.

Errors

HTTP Status Codes

Mailosaur uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the 5xx range indicate an error with Mailosaur’s servers (give us a shout in the unlikely event that you see one of those).

Error handling

In case of an error the server will return as much information as possible. In the case of a 401 or 404 error the status code gives as much information as you’d need. But for 400 errors Mailosaur will return a JSON object containing the structure below.

Note that our client libraries convert responses to appropriate language-specific objects.

Message object

Message objects represent an email or SMS received by Mailosaur and contain all the data you might need to perform any number of manual or automated tests.

{
  "id": "77061c9f-da47-4009-9f33-9715a3bbf00c",
  "received": "2019-08-06T17:44:07.197781+00:00",
  "subject": "Email subject line",
  "from": [{
    "name": "Acme",
    "email": "noreply@example.com"
  }],
  "to": [{
    "name": "Jane Doe",
    "email": "janedoe@abc1234.mailosaur.net"
  }],
  "cc": [],
  "bcc": [],
  "html": {
    "links": [{
      "href": "https://example.com/signup",
      "text": "Sign Up Now"
    }],
    "images": [],
    "body": "Lorem ipsum..."
  },
  "text": {
    "links": [{
      "href": "https://example.com/signup",
      "text": "https://example.com/signup"
    }],
    "body": "Lorem ipsum..."
  },
  "attachments": [],
  "metadata": {
    "headers": [{
      "field": "MIME-Version",
      "value": "1.0"
    }]
  },
  "server": "abcd1234"
}

Message summaries

When performing list or search queries, a truncated summary of each message is returned instead of the full object:

{
  "id": "77061c9f-da47-4009-9f33-9715a3bbf00c",
  "received": "2019-08-06T17:44:07.197781+00:00",
  "subject": "Email subject line",
  "from": [{
    "name": "Acme",
    "email": "noreply@example.com"
  }],
  "to": [{
    "name": "Jane Doe",
    "email": "janedoe@abc1234.mailosaur.net"
  }],
  "cc": [],
  "bcc": []
}

Attributes

• id string Unique identifier for the message.
• received datetime The date and time the message was received by Mailosaur, in ISO 8601 format.
• subject string The subject line of the message.
• from array The sender of the message. Note: This will usually only have one item, but technically it is possible to have multiple senders (yes, we were surprised too!)
  Show child attributes

  • name string The message sender's name.
  • email string The message sender's email address (always null for SMS messages).
  • phone string The message sender's telephone number (always null for email messages).
• to, cc and bcc array The recipients of the message. Note: cc and bcc will always be null for SMS messages.
  Show child attributes

  • name string The message recipient's name.
  • email string The message sender's email address (always null for SMS messages).
  • phone string The message sender's telephone number (always null for email messages).
• html object The HTML content of the message (always null for SMS messages).
  Show child attributes

  • body string HTML content.
  • image array Images found within the HTML content, each returned as an object with properties alt (the alternative text for the image) and src.
  • links array Hyperlinks, each returned as an object with properties text (the display text of the link) and href.
• text object The text content of the message.
  Show child attributes

  • body string Text content.
  • links array Hyperlinks, each returned as an object with properties text (the display text of the link) and href.
• attachments array The attachments associated with the message.
  Show child attributes

  • id string Unique identifier for the message.
  • contentType string The MIME type of the attachment.
  • fileName string The file name of the attachment.
  • contentId string The content identifier (for attachments that are embedded within the body of the message).
  • length string The file size, in bytes.
  • url string The URL from which the attachment can be downloaded.
• metadata object Additional information associated with the message.
  Show child attributes

  • headers array Message headers, each returned as an object with properties field and value.
• server string Unique identifier of the server containing the message.

Messages

Retrieve a message

Retrieves the detail for a single email message. Simply supply the unique identifier for the required message.

get https://mailosaur.com/api/messages/:id

Parameters

To get the ID of a message you need to call one of our other API calls which returns a list of messages. Each message in the list will contain an ID which you can use to make this call.

Response

Status: 200 OK

// Message object

Delete a message

Permanently deletes a message. This operation cannot be undone. Also deletes any attachments related to the message.

delete https://mailosaur.com/api/messages/:id

Parameters

Response

Status: 204 No Content

List all messages

Returns a list of your messages in summary form. The summaries are returned sorted by received date, with the most recently-received messages appearing first.

get https://mailosaur.com/api/messages?server=:server

Parameters

Response

Status: 200 OK

// Array of Message object

Delete all messages

Permanently deletes all messages held by the specified server. This operation cannot be undone. Also deletes any attachments related to each message.

delete https://mailosaur.com/api/messages?server=:server

Parameters

Response

Status: 204 No Content

Search for messages

Returns a list of message summaries matching the specified search criteria, in summary form. The summaries are returned sorted by received date, with the most recently-received messages appearing first.

post https://mailosaur.com/api/messages/search?server=:server

Parameters

Request

Message Summaries To get the full message content, including HTML & Text body content, you need to use the Retrieve a message endpoint. Alternatively you can search and retrieve in a single call by using our official client libraries.

{
  "sentFrom": "noreply@example.com",
  "sentTo": "someone@abcd1234.mailosaur.net",
  "subject": "Email address",
  "body": "Hey Alice,",
  "match": "ALL"
}

Response

Status: 200 OK

{
  "items": [
    // Message summary object
  ]
}

Files

Download an attachment

Downloads a single attachment. Simply supply the unique identifier for the required attachment.

get https://mailosaur.com/api/files/attachments/:id

Parameters

Response

Status: 200 OK

<< FileStream >>

Download EML

Downloads an EML file representing the specified email. Simply supply the unique identifier for the required email.

get https://mailosaur.com/api/files/email/:id

Parameters

Response

Status: 200 OK

<< FileStream >>

Spam

Perform a spam test

Perform spam testing on the specified email.

get https://mailosaur.com/api/analysis/spam/:email

Parameters

Response

Status: 200 OK

{
  "spamFilterResults": {
  "spamAssassin": [
    {
      "score": 0,
      "rule": "ABC123",
      "description": "ABC123"
    }
  ]},
  "score": 0
}

Servers

List all servers

Returns a list of your virtual SMTP servers. Servers are returned sorted in alphabetical order.

get https://mailosaur.com/api/servers

Response

Status: 200 OK

[
  {
    "id": "abcd1234",
    "name": "Server name",
    "users": [],
    "messages": 16
  }
]

Create a server

Creates a new virtual SMTP server and returns it.

post https://mailosaur.com/api/servers

Request

{
  "name": "My server"
}

Response

Status: 200 OK

{
    "id": "abcd1234",
    "name": "Server name",
    "users": [],
    "messages": 0
}

Retrieve a server

Retrieves the detail for a single server. Simply supply the unique identifier for the required server.

get https://mailosaur.com/api/servers/:id

Parameters

Response

Status: 200 OK

{
    "id": "abcd1234",
    "name": "Server name",
    "users": [],
    "messages": 0
}

Retrieve server password

Retrieves the password, for use with SMTP and POP3, for a single server. Simply supply the unique identifier for the required server.

get https://mailosaur.com/api/servers/:id/password

Parameters

Response

Status: 200 OK

{
    "value": "server-password"
}

Update a server

Updates a single server and returns it.

put https://mailosaur.com/api/servers/:id

Parameters

Request

{
    "id": "abcd1234",
    "name": "Server name",
    "users": [],
    "messages": 0
}

Response

Status: 200 OK

{
    "id": "abcd1234",
    "name": "Server name",
    "users": [],
    "messages": 0
}

Delete a server

Permanently deletes a server. This operation cannot be undone. Also deletes all messages and associated attachments within the server.

delete https://mailosaur.com/api/servers/:id

Parameters

Response

Status: 204 No Content