Mailosaur

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.

Run in Postman Run in Insomnia

Popular Setups

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).

CodeDescription
200 OKRequest was successful.
204 No ContentRequest was successful, no response content.
400 Bad RequestThe request could not be handled, often due to missing a required parameter.
401 UnauthorizedNo valid API key provided.
404 Not FoundThe requested resource doesn’t exist.
5XX Server ErrorsSomething went wrong at Mailosaur. (Give us a shout).

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.

FieldDescription
typeThe type of error returned.
messageA human-readable message providing more details about the error.
parametersA JSON object containing a key for each property name at fault, with a human-readable message per field.
modelThe request model that was sent and failed to be processed.

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

idstringUnique identifier for the message.
receiveddatetimeThe date and time the message was received by Mailosaur, in ISO 8601 format.
subjectstringThe subject line of the message.
fromarrayThe 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
namestringThe message sender's name.
emailstringThe message sender's email address (always null for SMS messages).
phonestringThe message sender's telephone number (always null for email messages).
to, cc and bccarrayThe recipients of the message. Note: cc and bcc will always be null for SMS messages.
Show child attributes
namestringThe message recipient's name.
emailstringThe message recipient's email address (always null for SMS messages).
phonestringThe message recipient's telephone number (always null for email messages).
htmlobjectThe HTML content of the message (always null for SMS messages).
Show child attributes
bodystringHTML content.
imagearrayImages found within the HTML content, each returned as an object with properties alt (the alternative text for the image) and src.
linksarrayHyperlinks, each returned as an object with properties text (the display text of the link) and href.
codesarrayVerification codes, each returned as an object with a single property, value.
textobjectThe text content of the message.
Show child attributes
bodystringText content.
linksarrayHyperlinks, each returned as an object with properties text (the display text of the link) and href.
codesarrayVerification codes, each returned as an object with a single property, value.
attachmentsarrayThe attachments associated with the message.
Show child attributes
idstringUnique identifier for the message.
contentTypestringThe MIME type of the attachment.
fileNamestringThe file name of the attachment.
contentIdstringThe content identifier (for attachments that are embedded within the body of the message).
lengthintegerThe file size, in bytes.
urlstringThe URL from which the attachment can be downloaded.
metadataobjectAdditional information associated with the message.
Show child attributes
headersarrayMessage headers, each returned as an object with properties field and value.
serverstringUnique identifier of the server containing the message.

Messages

Retrieve a message

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

Run in Postman Run in Insomnia

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

Parameters

NameTypeInDescription
idstringpathThe identifier of the message to be retrieved. This can be found via other API calls such as Search for messages.

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.

Run in Postman Run in Insomnia

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

Parameters

NameTypeInDescription
idstringpathThe identifier of the message to be deleted.

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.

Run in Postman Run in Insomnia

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

Parameters

NameTypeInDescription
serverstringqueryThe identifier of the server hosting the messages.
pageintqueryUsed in conjunction with itemsPerPage to support pagination.
itemsPerPageintqueryA limit on the number of results to be returned per page. Can be set between 1 and 1000 items, the default is 50.
receivedAfterdatetimequeryLimits results to only messages received after this date/time.

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.

Run in Postman Run in Insomnia

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

Parameters

NameTypeInDescription
serverstringqueryThe identifier of the server to be emptied.

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.

Run in Postman Run in Insomnia

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

Parameters

NameTypeInDescription
serverstringqueryThe identifier of the server hosting the messages.
pageintqueryUsed in conjunction with itemsPerPage to support pagination.
itemsPerPageintqueryA limit on the number of results to be returned per page. Can be set between 1 and 1000 items, the default is 50.
receivedAfterdatetimequeryLimits results to only messages received after this date/time.

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"
}
NameTypeDescription
sentFromstringThe full email address or phone number from which the target message was sent.
sentTostringThe full email address or phone number to which the target message was sent.
subjectstringThe value to seek within the target email’s subject line.
bodystringThe value to seek within the target message’s HTML or text body.
matchstringIf set to ALL (default), then only results that match all specified criteria will be returned. If set to ANY, results that match any of the specified criteria will be returned.

Response

Status: 200 OK
{
  "items": [
    // Message summary object
  ]
}

Forward a message

Forward an email or SMS message to a verified external email address. Supply the unique identifier for message you want to forward, as well as additional, relevant options.

Run in Postman Run in Insomnia

post https://mailosaur.com/api/messages/:id/forward

Parameters

NameTypeInDescription
idstringpathThe identifier of the message to be forwarded. This can be found via other API calls such as Search for messages.

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.

Request

{
  "to": "someone@example.com",
  "html": "<p>Hello world.</p>",
  "text": "Hello world."
}
NameTypeDescription
tostringThe verified external email address to which the message should be sent.
htmlstringAny HTML content to prefix the forwarded message with.
textstringAny plain text content to prefix the forwarded message with.

Response

Status: 200 OK
// Message object

Reply to a message

Reply to an email or SMS message. Supply the unique identifier for message you want to forward, as well as additional, relevant options.

Email replies can only be sent back to verified external email addresses. SMS replies can only contain approved phrases to prevent fraud.

Run in Postman Run in Insomnia

post https://mailosaur.com/api/messages/:id/reply

Parameters

NameTypeInDescription
idstringpathThe identifier of the message to be replied to. This can be found via other API calls such as Search for messages.

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.

Request

{
  "html": "<p>Hello world.</p>",
  "text": "Hello world.",
  "attachments": [{
    "fileName": "cat.png",
    "content": "{BASE64_ENCODED_FILE}",
    "contentType": "image/png"
  }]
}
NameTypeDescription
htmlstringAny HTML content to prefix the reply with.
textstringAny plain text content to prefix the reply with.
attachmentsarray of objectsAn object array of base64-encoded attachment objects (fileName, contentType, content).

Response

Status: 200 OK
// Message object

Send an email

You can only send emails to verified external email addresses. Supply the unique identifier for server you want to send from, as well as additional, relevant options.

Run in Postman Run in Insomnia

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

Parameters

NameTypeInDescription
serverstringqueryThe identifier of the server from which the email should be sent.

Request

{
  "from": "anything@SERVER_ID.mailosaur.net",
  "to": "someone@example.com",
  "html": "<p>Hello world.</p>",
  "text": "Hello world.",
  "send": true,
  "attachments": [{
    "fileName": "cat.png",
    "content": "{BASE64_ENCODED_FILE}",
    "contentType": "image/png"
  }]
}
NameTypeDescription
fromstringOptionally set the ‘from’ address (must be from a Mailosaur server domain - e.g. anything@abcd1234.mailosaur.net).
tostringThe verified external email address to which the email should be sent.
htmlstringHTML content for the email.
textstringPlain text content for the email.
sendbooleanIf not true, then the email will be created in your server, but will not be sent.
attachmentsarray of objectsAn object array of base64-encoded attachment objects (fileName, contentType, content).

Response

Status: 200 OK
// Message object

Files

Download an attachment

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

Run in Postman Run in Insomnia

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

Parameters

NameTypeInDescription
idstringpathThe identifier of the attachment to be downloaded.

Response

Status: 200 OK
<< FileStream >>

Download EML

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

Run in Postman Run in Insomnia

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

Parameters

NameTypeInDescription
idstringpathThe identifier of the email to be downloaded.

Response

Status: 200 OK
<< FileStream >>

Spam

Perform a spam test

Perform spam testing on the specified email.

Run in Postman Run in Insomnia

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

Parameters

NameTypeInDescription
emailstringpathThe identifier of the email to be analysed.

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.

Run in Postman Run in Insomnia

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.

Run in Postman Run in Insomnia

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.

Run in Postman Run in Insomnia

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

Parameters

NameTypeInDescription
idstringpathThe identifier of the server to be retrieved.

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.

Run in Postman Run in Insomnia

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

Parameters

NameTypeInDescription
idstringpathThe identifier of the server.

Response

Status: 200 OK
{
    "value": "server-password"
}

Update a server

Updates a single server and returns it.

Run in Postman Run in Insomnia

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

Parameters

NameTypeInDescription
idstringpathThe identifier of the server to be updated.

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.

Run in Postman Run in Insomnia

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

Parameters

NameTypeInDescription
idstringpathThe identifier of the server to be deleted.

Response

Status: 204 No Content

Virtual Security Devices

Retrieve one-time password

Retrieves the one-time password for a given base32-encoded secret.

Run in Postman Run in Insomnia

post https://mailosaur.com/api/devices/otp

Request

{
  "sharedSecret": "ONSWG4TFOQYTEMY="
}

Response

Status: 200 OK
{
    "code": "123456",
    "expires": "2022-01-01T00:00:00Z"
}

List all devices

Returns a list of your virtual security devices.

Run in Postman Run in Insomnia

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

Response

Status: 200 OK
[
  {
    "id": "abcd1234",
    "name": "Device name"
  }
]

Create a device

Creates a new virtual security device and returns it.

Run in Postman Run in Insomnia

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

Request

{
  "name": "My device",
  "sharedSecret": "ONSWG4TFOQYTEMY="
}

Response

Status: 200 OK
{
    "id": "abcd1234",
    "name": "My device"
}

Retrieve OTP for an existing device

Retrieves the current one-time password for an existing virtual security device. Simply supply the unique identifier for the required device.

Run in Postman Run in Insomnia

get https://mailosaur.com/api/devices/:id/otp

Parameters

NameTypeInDescription
idstringpathThe identifier of the device to be retrieved.

Response

Status: 200 OK
{
    "code": "123456",
    "expires": "2022-01-01T00:00:00Z"
}

Delete a device

Permanently deletes a device. This operation cannot be undone.

Run in Postman Run in Insomnia

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

Parameters

NameTypeInDescription
idstringpathThe identifier of the device to be deleted.

Response

Status: 204 No Content

Usage

Retrieve account limits

Retrieve account usage limits. Details the current limits and usage for your account. This endpoint requires authentication with an account-level API key.

Run in Postman Run in Insomnia

get https://mailosaur.com/api/usage/limits

Response

Status: 200 OK
{
  "servers": {
    "current": 27,
    "limit": 50
  },
  "users": {
    "current": 16,
    "limit": 25
  },
  "email": {
    "current": 12356,
    "limit": 20000
  },
  "sms": {
    "current": 271,
    "limit": 500
  },
  "previews": {
    "current": 89,
    "limit": 200
  },
  "numbers": {
    "current": 2,
    "limit": 5
  }
}

List usage transactions

Retrieves the last 31 days of transactional usage. This endpoint requires authentication with an account-level API key.

Run in Postman Run in Insomnia

get https://mailosaur.com/api/usage/transactions

Response

Status: 200 OK
{
  "items": [
    {
      "timestamp": "2021-01-31T00:00:00Z",
      "email": 2000,
      "sms": 51,
      "previews": 0
    }
  ]
}