API

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

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

CODE DESCRIPTION
200 OK Request was successful.
204 No Content Request was successful, no response content.
400 Bad Request The request could not be handled, often due to missing a required parameter.
401 Unauthorized No valid API key provided.
404 Not Found The requested resource doesn’t exist.
5XX Server Errors Something 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.

FIELD DESCRIPTION
type The type of error returned.
message A human-readable message providing more details about the error.
parameters A JSON object containing a key for each property name at fault, with a human-readable message per field.
model The request model that was sent and failed to be processed.

Email and SMS testing

The Messages API allows you to list, search, view, modify and create email and SMS messages within your Mailosaur account.

Retrieve a message

If you are using one of Mailosaur’s client libraries, we highly recommend using the .Get method instead of .GetById, as it automatically waits for results to arrive!

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

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.

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description
    The identifier of the message to be retrieved. This can be found via other API calls such as List/Search.
Postman iconInsomnia icon
GET /api/messages/:id
curl \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/messages/MESSAGE_ID
const message = await mailosaur.messages.getById('MESSAGE_ID');
cy.mailosaurGetMessageById('MESSAGE_ID')
  .then(message => {
      cy.log(message.subject); // "Example"
  });
message = mailosaur.messages.get_by_id("MESSAGE_ID")
Message message = mailosaur.messages().getById("MESSAGE_ID");
var message = mailosaur.Messages.GetById("MESSAGE_ID");
message = mailosaur.messages.get_by_id('MESSAGE_ID')
$message = $mailosaur->messages->getById('MESSAGE_ID');
$message = $mailosaur->messages->getById('MESSAGE_ID');
{
    "id": "77061c9f-da47-4009-9f33-9715a3bbf00c",
    "received": "2019-08-06T17:44:07.197781+00:00",
    "type": "Email",
    "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"
}

Delete a message

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

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description
    The identifier of the message to be deleted.
Postman iconInsomnia icon
DELETE /api/messages/:id
curl \
  -X DELETE \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/messages/MESSAGE_ID
await mailosaur.messages.del('MESSAGE_ID');
cy.mailosaurDeleteMessage('MESSAGE_ID');
mailosaur.messages.delete("MESSAGE_ID")
mailosaur.messages().delete("MESSAGE_ID");
mailosaur.Messages.Delete("MESSAGE_ID");
mailosaur.messages.delete('MESSAGE_ID')
$mailosaur->messages->delete('MESSAGE_ID');
m.Messages.Delete("MESSAGE_ID")

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.

Query parameters

  • Name
    server
    Type
    string
    Required
    required
    Description
    The identifier of the server hosting the messages.
  • Name
    receivedAfter
    Type
    date/time
    Description
    Limits results to only messages received after this date/time.
  • Name
    page
    Type
    integer
    Description
    Used in conjunction with `itemsPerPage` to support pagination.
  • Name
    itemsPerPage
    Type
    integer
    Description
    A limit on the number of results to be returned per page. Can be set between 1 and 1000 items, the default is 50.
  • Name
    dir
    Type
    string
    Description
    Optionally limits results based on the direction (`Sent` or `Received`), with the default being `Received`.
Postman iconInsomnia icon
GET /api/messages?server=:server
curl \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/messages?server=SERVER_ID
const result = await mailosaur.messages.list('SERVER_ID');
console.log(result.items[0].subject); // "Example"
cy.mailosaurListMessages('SERVER_ID').then(result => {
  cy.log(result.items[0].subject); // "Example"
});
result = mailosaur.messages.list("SERVER_ID")
print result.items[0].subject # "Example"
MessageListParams params = new MessageListParams();
params.withServer("SERVER_ID");
MessageListResult result = mailosaur.messages().list(params);
var result = mailosaur.Messages.List("SERVER_ID");
Console.WriteLine(result.Items[0].Subject); // "Example"
result = mailosaur.messages.list('SERVER_ID')
print(result.items[0].subject) # "Example"
$result = $mailosaur->messages->all('SERVER_ID');
print($result->items[0]->subject); // "Example"
result := m.Messages.List("SERVER_ID")
fmt.Println(result.Items[0].Subject) // "Example"
[
    {
        "id": "77061c9f-da47-4009-9f33-9715a3bbf00c",
        "received": "2019-08-06T17:44:07.197781+00:00",
        "type": "Email",
        "subject": "Email subject line",
        "from": [{
            "name": "Acme",
            "email": "noreply@example.com"
        }],
        "to": [{
            "name": "Jane Doe",
            "email": "janedoe@abc1234.mailosaur.net"
        }],
        "cc": [],
        "bcc": []
    }
]

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.

Query parameters

  • Name
    server
    Type
    string
    Required
    required
    Description
    The identifier of the server to be emptied.
Postman iconInsomnia icon
DELETE /api/messages?server=:server
curl \
  -X DELETE \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/messages?server=SERVER_ID
await mailosaur.messages.deleteAll('SERVER_ID');
cy.mailosaurDeleteAllMessages('SERVER_ID');
mailosaur.messages.delete_all("SERVER_ID")
mailosaur.messages().deleteAll("SERVER_ID");
mailosaur.Messages.DeleteAll("SERVER_ID");
mailosaur.messages.delete_all('SERVER_ID')
$mailosaur->messages->deleteAll('SERVER_ID');
m.Messages.DeleteAll("SERVER_ID")

Search for messages

If you are using one of Mailosaur’s client libraries, we highly recommend using the .Get method instead of .Search, as it automatically waits for results to arrive. It also returns the whole email/SMS, rather than just a message summary.

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.

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.

Query parameters

  • Name
    server
    Type
    string
    Required
    required
    Description
    The identifier of the server hosting the messages.
  • Name
    receivedAfter
    Type
    date/time
    Description
    Limits results to only messages received after this date/time.
  • Name
    page
    Type
    integer
    Description
    Used in conjunction with `itemsPerPage` to support pagination.
  • Name
    itemsPerPage
    Type
    integer
    Description
    A limit on the number of results to be returned per page. Can be set between 1 and 1000 items, the default is 50.
  • Name
    dir
    Type
    string
    Description
    Optionally limits results based on the direction (`Sent` or `Received`), with the default being `Received`.

Body parameters

  • Name
    sentFrom
    Type
    string
    Description
    The full email address or phone number from which the target message was sent.
  • Name
    sentTo
    Type
    string
    Description
    The full email address or phone number to which the target message was sent.
  • Name
    subject
    Type
    string
    Description
    The value to seek within the target email’s subject line.
  • Name
    body
    Type
    string
    Description
    The value to seek within the target message’s HTML or text body.
  • Name
    match
    Type
    string
    Description
    If 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.
Postman iconInsomnia icon
POST /api/messages/search?server=:server
curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"sentTo":"someone@SERVER_ID.mailosaur.net"}' \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/messages/search?server=SERVER_ID
const result = await mailosaur.messages.search('SERVER_ID', {
  sentTo: 'someone@SERVER_ID.mailosaur.net'
});

// Get the most recent match
const message = result.items[0];

console.log('Subject:', message.subject);
cy.mailosaurSearchMessages('SERVER_ID', {
  sentTo: 'someone@SERVER_ID.mailosaur.net'
}).then(result => {
  // Get the most recent match
  const message = result.items[0];

  cy.log(`Subject: ${message.subject}`);
});
from mailosaur.models import SearchCriteria

# ...

criteria = SearchCriteria()
criteria.sent_to = "someone@SERVER_ID.mailosaur.net"

result = mailosaur.messages.search('SERVER_ID', criteria)

# Get the most recent match
message = result.items[0]

print('Subject: ' + message.subject)
MessageSearchParams params = new MessageSearchParams();
params.withServer("SERVER_ID");

SearchCriteria criteria = new SearchCriteria();
criteria.withSentTo("someone@SERVER_ID.mailosaur.net");

MessageListResult result = mailosaur.messages().search(params, criteria);

// Get the most recent match
MessageSummary message = result.items().get(0);

System.out.println("Subject: " + message.subject());
var result = mailosaur.Messages.Search("SERVER_ID", new SearchCriteria() {
  SentTo = "someone@SERVER_ID.mailosaur.net"
});

// Get the most recent match
var message = result.Items[0];

Console.WriteLine("Subject: " + message.Subject);
criteria = Mailosaur::Models::SearchCriteria.new()
criteria.sent_to = "someone@SERVER_ID.mailosaur.net"

result = mailosaur.messages.search("SERVER_ID", criteria)

# Get the most recent match
message = result.items[0]

print('Subject: ' + message.subject)
$criteria = new SearchCriteria();
$criteria->sentTo = 'someone@SERVER_ID.mailosaur.net';

$result = $mailosaur->messages->search('SERVER_ID', $criteria);

# Get the most recent match
$message = $result->items[0];

print('Subject: ' . $message->subject);
params := &mailosaur.MessageListParams {
  Server: server,
}

criteria := &mailosaur.SearchCriteria {
  SentTo: "someone@SERVER_ID.mailosaur.net",
}

result, err := m.Messages.Search(params, criteria)

if (err != nil) {
  // Handle err
}

// Get the most recent match
message := result.Items[0]

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

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.

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.

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description
    The identifier of the message to be forwarded. This can be found via other API calls such as Search for messages.

Body parameters

  • Name
    to
    Type
    string
    Required
    required
    Description
    The verified external email address to which the message should be sent.
  • Name
    subject
    Type
    string
    Description
    Optionally override an email's subject line.
  • Name
    html
    Type
    string
    Description
    Any HTML content to prefix the forwarded message with.
  • Name
    text
    Type
    string
    Description
    Any plain text content to prefix the forwarded message with.
Postman iconInsomnia icon
POST /api/messages/:id/forward
curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"to":"someone@example.com","text":"Example"}' \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/messages/MESSAGE_ID/forward
// MESSAGE_ID: The `id` of the message you want to forward
await mailosaur.messages.forward('MESSAGE_ID', {
  to: 'someone@example.com', // must be a verified address
  html: '<p>Hello world.</p>'
});
// MESSAGE_ID: The `id` of the message you want to reply to
cy.mailosaurForwardMessage('MESSAGE_ID', {
  to: 'someone@example.com', // must be a verified address
  html: '<p>Hello world.</p>'
})
recipient = "someone@example.com" # must be a verified address
body = "<p>Hello world.</p>"
options = MessageForwardOptions(recipient, html=body)

# MESSAGE_ID: The `id` of the message you want to forward
mailosaur.messages.forward("MESSAGE_ID", options)
MessageForwardOptions options = new MessageForwardOptions();
options.withTo("someone@example.com") // must be a verified address
  .withHtml("<p>Hello world.</p>");

// MESSAGE_ID: The `id` of the message you want to forward
mailosaur.messages().forward("MESSAGE_ID", options);
// MESSAGE_ID: The `id` of the message you want to forward
mailosaur.Messages.Forward("MESSAGE_ID", new MessageForwardOptions()
  {
      To = "someone@example.com", // must be a verified address
      Html = "<p>Hello world.</p>"
  }
);
options = Mailosaur::Models::MessageForwardOptions.new()
options.to = 'someone@example.com' # must be a verified address
options.html = '<p>Hello world.</p>'

# MESSAGE_ID: The `id` of the message you want to forward
mailosaur.messages.forward('MESSAGE_ID', options)
$options = new MessageForwardOptions();
$options->to = 'someone@example.com'; // must be a verified address
$options->html = '<p>Hello world.</p>';

// MESSAGE_ID: The `id` of the message you want to forward
$mailosaur->messages->forward('MESSAGE_ID', $options);
// MESSAGE_ID: The `id` of the message you want to forward
m.Messages.Forward("MESSAGE_ID", &MessageForwardOptions{
  To:   "someone@example.com", // must be a verified address
  Html: "<p>Hello world.</p>",
})
{
    "id": "77061c9f-da47-4009-9f33-9715a3bbf00c",
    "received": "2019-08-06T17:44:07.197781+00:00",
    "type": "Email",
    "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"
}

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 address. SMS replies can only contain approved phrases to prevent fraud.

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.

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description
    The identifier of the message to be replied to. This can be found via other API calls such as Search for messages.

Body parameters

  • Name
    subject
    Type
    string
    Description
    Optionally override an email's subject line.
  • Name
    html
    Type
    string
    Description
    Any HTML content to prefix the reply with.
  • Name
    text
    Type
    string
    Description
    Any plain text content to prefix the reply with.
  • Name
    attachments
    Type
    array
    Description
    An object array of base64-encoded attachment objects (`fileName`, `contentType`, `content`).
Postman iconInsomnia icon
POST /api/messages/:id/reply
curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"text":"Example"}' \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/messages/MESSAGE_ID/reply
// MESSAGE_ID: The `id` of the message you want to reply to
await mailosaur.messages.reply('MESSAGE_ID', {
  html: '<p>Hello world.</p>'
});
// MESSAGE_ID: The `id` of the message you want to reply to
cy.mailosaurReplyToMessage('MESSAGE_ID', {
  html: '<p>Hello world.</p>'
});
body = "<p>Hello world.</p>"
options = MessageReplyOptions(html=body)

# MESSAGE_ID: The `id` of the message you want to reply to
mailosaur.messages.reply("MESSAGE_ID", options)
MessageReplyOptions options = new MessageReplyOptions();
options.withHtml("<p>Hello world.</p>");

// MESSAGE_ID: The `id` of the message you want to reply to
mailosaur.messages().reply("MESSAGE_ID", options);
// MESSAGE_ID: The `id` of the message you want to reply to
mailosaur.Messages.Reply("MESSAGE_ID", new MessageReplyOptions()
  {
      Html = "<p>Hello world.</p>"
  }
);
options = Mailosaur::Models::MessageReplyOptions.new()
options.html = '<p>Hello world.</p>'

# MESSAGE_ID: The `id` of the message you want to reply to
mailosaur.messages.reply('MESSAGE_ID', options)
$options = new MessageReplyOptions();
$options->html = '<p>Hello world.</p>';

// MESSAGE_ID: The `id` of the message you want to reply to
$mailosaur->messages->reply('MESSAGE_ID', $options);
// MESSAGE_ID: The `id` of the message you want to reply to
m.Messages.Reply("MESSAGE_ID", &MessageReplyOptions{
  Html: "<p>Hello world.</p>",
})
{
    "id": "77061c9f-da47-4009-9f33-9715a3bbf00c",
    "received": "2019-08-06T17:44:07.197781+00:00",
    "type": "Email",
    "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"
}

Send an email

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

Query parameters

  • Name
    server
    Type
    string
    Required
    required
    Description
    The identifier of the server from which the email should be sent.

Body parameters

  • Name
    to
    Type
    string
    Required
    required
    Description
    The verified external email address to which the email should be sent.
  • Name
    from
    Type
    string
    Description
    Optionally overrides of the message’s ‘from’ address. This **must** be an address ending with `YOUR_SERVER.mailosaur.net`, such as `my-emails @a1bcdef2.mailosaur.net`.
  • Name
    subject
    Type
    string
    Required
    required
    Description
    The subject line for an email.
  • Name
    html
    Type
    string
    Description
    HTML content for the email.
  • Name
    text
    Type
    string
    Description
    Plain text content for the email.
  • Name
    send
    Type
    boolean
    Description
    If not `true`, then the email will be created in your server, but will not be sent.
  • Name
    attachments
    Type
    array
    Description
    An object array of base64-encoded attachment objects (`fileName`, `contentType`, `content`).
Postman iconInsomnia icon
POST /api/messages?server=:server
curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"to":"someone@example.com","subject":"Email from Mailosaur","text":"Example","send":true}' \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/messages?server=SERVER_ID
await mailosaur.messages.create('SERVER_ID', {
  to: 'someone@example.com', // must be a verified address
  subject: 'Email from Mailosaur',
  html: '<p>Hello world.</p>',
  send: true
});
cy.mailosaurCreateMessage('SERVER_ID', {
  to: 'someone@example.com', // must be a verified address
  subject: 'Email from Mailosaur',
  html: '<p>Hello world.</p>',
  send: true
});
recipient = "someone@example.com" # must be a verified address
subject = "Email from Mailosaur"
body = "<p>Hello world.</p>"
options = MessageCreateOptions(
  recipient, True, subject, html=body)

mailosaur.messages.create("SERVER_ID", options)
MessageCreateOptions options = new MessageCreateOptions();
options.withTo("someone@example.com") // must be a verified address
  .withSubject("Email from Mailosaur")
  .withHtml("<p>Hello world.</p>")
  .withSend(true);

mailosaur.messages().create("SERVER_ID", options);
mailosaur.Messages.Create("SERVER_ID", new MessageCreateOptions()
  {
      To = "someone@example.com", // must be a verified address
      Subject = "Email from Mailosaur",
      Html = "<p>Hello world.</p>",
      Send = true
  }
);
options = Mailosaur::Models::MessageCreateOptions.new()
options.to = 'someone@example.com' # must be a verified address
options.subject = 'Email from Mailosaur'
options.html = '<p>Hello world.</p>'
options.send = true

mailosaur.messages.create('SERVER_ID', options)
$options = new MessageCreateOptions();
$options->to = 'someone@example.com'; // must be a verified address
$options->subject = 'Email from Mailosaur';
$options->html = '<p>Hello world.</p>';
$options->send = TRUE;

$mailosaur->messages->create('SERVER_ID', $options);
m.Messages.Create("SERVER_ID", &MessageCreateOptions{
  To:      "someone@example.com", // must be a verified address
  Subject: "Email from Mailosaur",
  Html:    "<p>Hello world.</p>",
  Send:    true,
})
{
    "id": "77061c9f-da47-4009-9f33-9715a3bbf00c",
    "received": "2019-08-06T17:44:07.197781+00:00",
    "type": "Email",
    "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"
}

Authenticator (2FA)

The Authenticator (2FA devices) API allows you to generate one-time passwords (OTPs) and virtual security devices, for the purpose of testing authentication systems.

Retrieve one-time password

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

Body parameters

  • Name
    sharedSecret
    Type
    string
    Required
    required
    Description
    The base32-encoded shared secret to generate a one-time password for.
Postman iconInsomnia icon
POST /api/devices/otp
curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"sharedSecret":"ONSWG4TFOQYTEMY="}' \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/devices/otp
const sharedSecret = 'ONSWG4TFOQYTEMY=';
const currentOtp = await mailosaur.devices.otp(sharedSecret);

console.log(currentOtp.code); // "564214"
const sharedSecret = 'ONSWG4TFOQYTEMY=';

cy.mailosaurGetDeviceOtp(sharedSecret)
  .then(currentOtp => {
      cy.log(currentOtp.code); // "564214" 
  });
shared_secret = "ONSWG4TFOQYTEMY="
current_otp = mailosaur.devices.otp(shared_secret)

print current_otp.code # "564214"
String sharedSecret = "ONSWG4TFOQYTEMY=";
String currentOtp = mailosaur.devices().otp(sharedSecret);

System.out.println(currentOtp.code); // "564214"
var sharedSecret = "ONSWG4TFOQYTEMY=";
var currentOtp = mailosaur.Devices.Otp(sharedSecret);

Console.WriteLine(currentOtp.code); // "564214"
shared_secret = 'ONSWG4TFOQYTEMY='
current_otp = mailosaur.devices.otp(shared_secret)

print(current_otp.code) # "564214"
$sharedSecret = 'ONSWG4TFOQYTEMY=';
$currentOtp = $mailosaur->devices->otp($sharedSecret);

print($currentOtp->code); // "564214"
sharedSecret := "ONSWG4TFOQYTEMY="

currentOtp := m.Devices.Otp(sharedSecret)
fmt.Println(currentOtp.Code) // "564214"
{
  "code": "123456",
  "expires": "2022-01-01T00:00:00Z"
}

List all devices

Returns a list of your virtual security devices.

Postman iconInsomnia icon
GET /api/devices
curl \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/devices
const result = await mailosaur.devices.list();
console.log(result.items[0].name); // "Example"
cy.mailosaurListDevices().then(result => {
  cy.log(result.items[0].name); // "Example"
});
result = mailosaur.devices.list()
print result.items[0].name # "Example"
DeviceListResult result = mailosaur.devices().list();
var result = mailosaur.Devices.List();
Console.WriteLine(result.Items[0].Name); // "Example"
result = mailosaur.devices.list()
print(result.items[0].name) # "Example"
$result = $mailosaur->devices->all();
print($result->items[0]->name); // "Example"
result := m.Devices.List()
fmt.Println(result.Items[0].Name) // "Example"
[
    {
        "id": "abcd1234",
        "name": "Device name"
    }
]

Create a device

Creates a new virtual security device and returns it.

Body parameters

  • Name
    name
    Type
    string
    Required
    required
    Description
    A name for the virtual device.
  • Name
    sharedSecret
    Type
    string
    Required
    required
    Description
    The base32-encoded shared secret to generate a one-time password for.
Postman iconInsomnia icon
POST /api/devices
curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"name":"Example","sharedSecret":"ONSWG4TFOQYTEMY="}' \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/devices
await mailosaur.devices.create({
  name: 'Example',
  sharedSecret: 'ONSWG4TFOQYTEMY='
});
cy.mailosaurCreateDevice({
  name: 'Example',
  sharedSecret: 'ONSWG4TFOQYTEMY='
});
name = "Example"
shared_secret = "ONSWG4TFOQYTEMY="
options = DeviceCreateOptions(name, shared_secret)

mailosaur.devices.create(options)
DeviceCreateOptions options = new DeviceCreateOptions();
options.withName("Example")
  .withSharedSecret("ONSWG4TFOQYTEMY=");

mailosaur.devices().create(options);
mailosaur.Devices.Create(new DeviceCreateOptions()
  {
      Name = "Example",
      SharedSecret = "ONSWG4TFOQYTEMY="
  }
);
options = Mailosaur::Models::DeviceCreateOptions.new()
options.name = 'Example'
options.shared_secret = 'ONSWG4TFOQYTEMY='

mailosaur.devices.create(options)
$options = new DeviceCreateOptions();
$options->name = 'Example';
$options->sharedSecret = 'ONSWG4TFOQYTEMY=';

$mailosaur->devices->create($options);
m.Devices.Create(&DeviceCreateOptions{
  Name:         "Example",
  SharedSecret: "ONSWG4TFOQYTEMY=",
})
{
    "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.

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description
    The identifier of the device to be retrieved.
Postman iconInsomnia icon
GET /api/devices/:id/otp
curl \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/devices/DEVICE_ID/otp
const currentOtp = await mailosaur.devices.otp('DEVICE_ID');
console.log(currentOtp.code); // "564214"
cy.mailosaurGetDeviceOtp('DEVICE_ID')
  .then(currentOtp => {
      cy.log(currentOtp.code); // "564214" 
  });
current_otp = mailosaur.devices.otp("DEVICE_ID")
print current_otp.code # "564214"
String currentOtp = mailosaur.devices().otp("DEVICE_ID");
System.out.println(currentOtp.code); // "564214"
var currentOtp = mailosaur.Devices.Otp("DEVICE_ID");
Console.WriteLine(currentOtp.code); // "564214"
current_otp = mailosaur.devices.otp('DEVICE_ID')
print(current_otp.code) # "564214"
$currentOtp = $mailosaur->devices->otp('DEVICE_ID');
print($currentOtp->code); // "564214"
currentOtp := m.Devices.Otp("DEVICE_ID")
fmt.Println(currentOtp.Code) // "564214"
{
    "code": "123456",
    "expires": "2022-01-01T00:00:00Z"
}

Delete a device

Permanently deletes a device. This operation cannot be undone.

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description
    The identifier of the device to be deleted.
Postman iconInsomnia icon
DELETE /api/devices/:id
curl \
  -X DELETE \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/devices/DEVICE_ID
await mailosaur.devices.del('DEVICE_ID');
cy.mailosaurDeleteDevice('DEVICE_ID');
mailosaur.devices.delete("DEVICE_ID")
mailosaur.devices().delete("DEVICE_ID");
mailosaur.Devices.Delete("DEVICE_ID");
mailosaur.devices.delete('DELETE_ID')
$mailosaur->devices->delete('DEVICE_ID');
m.Devices.Delete("DEVICE_ID")

Files

The Files API allows you to download files, such as message attachments, from Mailosaur.

Download an attachment

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

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description
    The identifier of the attachment to be downloaded.
Postman iconInsomnia icon
GET /api/files/attachments/:id
curl \
  -o example.png \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/files/attachments/ATTACHMENT_ID
const fs = require('fs');

// ...

const file = await mailosaur.files.getAttachment('ATTACHMENT_ID');
fs.writeFileSync('example.png', file);
cy.mailosaurDownloadAttachment('ATTACHMENT_ID').then(file => {
  cy.writeFile('example.png', file, 'binary')
})
file = mailosaur.files.get_attachment('ATTACHMENT_ID').content
f = open('example.png', 'wb')
f.write(file)
f.close()
byte[] file = mailosaur.files().getAttachment("ATTACHMENT_ID");
Files.write(Paths.get("example.png"), file);
var file = mailosaur.Files.GetAttachment("ATTACHMENT_ID");
File.WriteAllBytes("example.png", file);
file = mailosaur.files.get_attachment('ATTACHMENT_ID')
File.open(first_attachment.file_name, 'wb') { |fp| fp.write(file) }
$file = $mailosaur->files->getAttachment("ATTACHMENT_ID");
$f = fopen("example.png", "w") or die("Unable to open file!");
fwrite($f, $file);
fclose($f);
var file, _ = m.Files.GetAttachment("ATTACHMENT_ID")
var err = os.WriteFile("example.png", file, 0644)
if err != nil {
  // handle error
}

Download EML

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

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description
    The identifier of the email to be downloaded.
Postman iconInsomnia icon
GET /api/files/email/:id
curl \
  -o example.eml \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/files/email/MESSAGE_ID
const fs = require('fs');

// ...

const file = await mailosaur.files.getEmail('MESSAGE_ID');
fs.writeFileSync('example.eml', file);
cy.mailosaurDownloadMessage('MESSAGE_ID').then(file => {
  cy.writeFile('example.eml', file, 'binary')
})
file = mailosaur.files.get_email('MESSAGE_ID').content
f = open('example.eml', 'wb')
f.write(file)
f.close()
byte[] file = mailosaur.files().getEmail("MESSAGE_ID");
Files.write(Paths.get("example.eml"), file);
var file = mailosaur.Files.GetEmail("MESSAGE_ID");
File.WriteAllBytes("example.eml", file);
file = mailosaur.files.get_email('MESSAGE_ID')
File.open(first_attachment.file_name, 'wb') { |fp| fp.write(file) }
$file = $mailosaur->files->getEmail("MESSAGE_ID");
$f = fopen("example.eml", "w") or die("Unable to open file!");
fwrite($f, $file);
fclose($f);
var file, _ = m.Files.GetEmail("MESSAGE_ID")
var err = os.WriteFile("example.eml", file, 0644)
if err != nil {
  // handle error
}

Analysis

The Analysis API allows you to analyse messages in more detail. For example, running a SpamAssassin report.

Perform a deliverability check

Generates a a deliverability report for the specified email. The domain of the sender is checked to ensure the deliverability of the email. Content of the email is also checked to highlight issues that may cause the email to be marked as illegitimate. Content is also checked via SpamAssassin which is one of the most common spam checkers on the market, these results can be used to understand how common spam checkers will view your email.

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description
    The identifier of the email to be analyzed.
Postman iconInsomnia icon
GET /api/analysis/deliverability/:id
curl \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/analysis/deliverability/MESSAGE_ID
const result = await mailosaur.analysis.deliverability(message.id)

console.log(result.spf.result) // "Pass"

result.spamAssassin.forEach(r => {
  console.log(r.rule)
  console.log(r.description)
  console.log(r.score)
})
cy.mailosaurGetDeliverabilityReport().then(result => {
  cy.log(result.spf.result) // "Pass"

  result.spamAssassin.forEach(r => {
    cy.log(r.rule)
    cy.log(r.description)
    cy.log(r.score)
  })
})
result = mailosaur.analysis.deliverability(message.id)

print(result.spf.result) // "Pass"

for r in result.spam_assassin:
  print(r.rule)
  print(r.description)
  print(r.score)
DeliverabilityReport result = client.analysis().deliverability(message.id());

System.out.println(result.spf().result()); // "Pass"

for (SpamAssassinRule rule : result.spamFilterResults().spamAssassin()) {
    System.out.println(rule.rule());
    System.out.println(rule.description());
}
var result = mailosaur.Analysis.Deliverability(message.Id);

Console.WriteLine(result.spf.result) // "Pass"

foreach (var r in result.SpamAssassin) {
  Console.WriteLine(r.Rule);
  Console.WriteLine(r.Description);
  Console.WriteLine(r.Score);
}
result = mailosaur.analysis.deliverability(message.id)

puts(result.spf.result) // "Pass"

for r in result.spam_assassin do
  puts(r.rule)
  puts(r.description)
  puts(r.score)
end
$result = $mailosaur->analysis->deliverability($message->id);

print($result->spf->result) // "Pass"

foreach ($result->spamAssassin as &$r) {
  print($r->rule);
  print($r->description);
  print($r->score);
}
result, _ := m.Analysis.Deliverability(message.Id)
fmt.Println(result.Spf.Result) // "Pass"

for _, r := range result.SpamAssassin {
  fmt.Println(r.Rule)
  fmt.Println(r.Description)
  fmt.Println(r.Score)
}
let result = try await EmailsTestsSetup.client.analysis.deliverability(email: message.id)

print(result.spf?.result) // "Pass"

for rule in result.spamAssassin {
    print(rule.rule)
    print(rule.description)
    print(rule.score)
}
{
    "spf": {
        "result": "Pass",
        "description": null,
        "rawValue": null,
        "tags": {}
    },
    "dkim": [
        {
            "result": "Pass",
            "description": null,
            "rawValue": null,
            "tags": {}
        }
    ],
    "dmarc": {
        "result": "Pass",
        "description": null,
        "rawValue": "v=DMARC1; p=reject; rua=mailto:dmarc@abc1234.mailosaur.net;",
        "tags": {
            "v": "DMARC1",
            "p": "reject",
            "rua": "mailto:dmarc@abc1234.mailosaur.net"
        }
    },
    "blockLists": [
        {
            "id": "ABC123",
            "name": "ABC",
            "result": "Pass"
        },
        {
            "id": "DEF123",
            "name": "DEF",
            "result": "Warning"
        },
        {
            "id": "GHI123",
            "name": "GHI",
            "result": "Fail"
        },
    ],
    "content": {
        "embed": false,
        "iframe": false,
        "object": false,
        "script": false,
        "shortUrls": false,
        "textSize": 123,
        "totalSize": 3456,
        "missingAlt": false,
        "missingListUnsubscribe": false
    },
    "dnsRecords": {
        "a": [
            "mailosaur.net. 30 IN A 192.168.1.1"
        ],
        "mx": [
            "mailosaur.net. 30 IN MX 0 mailosaur.net."
        ],
        "ptr": []
    },
    "spamAssassin": {
        "score": 0,
        "result": "Pass",
        "rules": [
            {
                "score": 0.0,
                "rule": "ABC123",
                "description": "ABC123"
            }
        ]
    }
}

Inboxes (servers)

The Servers API allows you to list, view, create, and modify the servers (inboxes) that store your email and SMS messages.

List all servers

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

Postman iconInsomnia icon
GET /api/servers
curl \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/servers
const result = await mailosaur.servers.list();
console.log(result.items[0].name); // "Example"
cy.mailosaurListServers().then(result => {
  cy.log(result.items[0].name); // "Example"
});
result = mailosaur.servers.list()
print result.items[0].name # "Example"
ServerListResult result = mailosaur.servers().list();
var result = mailosaur.Servers.List();
Console.WriteLine(result.Items[0].Name); // "Example"
result = mailosaur.servers.list()
print(result.items[0].name) # "Example"
$result = $mailosaur->servers->all();
print($result->items[0]->name); // "Example"
result := m.Servers.List()
fmt.Println(result.Items[0].Name) // "Example"
[
    {
        "id": "abcd1234",
        "name": "Server name",
        "users": [],
        "messages": 16
    }
]

Create a server

Creates a new virtual SMTP server and returns it.

Body parameters

  • Name
    name
    Type
    string
    Required
    required
    Description
    The name of the server.
Postman iconInsomnia icon
POST /api/servers
curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"name":"Example"}' \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/servers
await mailosaur.servers.create({
  name: 'Example'
});
cy.mailosaurCreateServer({
  name: 'Example'
});
name = "Example"
options = ServerCreateOptions(name)

mailosaur.servers.create(options)
ServerCreateOptions options = new ServerCreateOptions();
options.withName("Example");

mailosaur.servers().create(options);
mailosaur.Servers.Create(new ServerCreateOptions()
  {
      Name = "Example"
  }
);
options = Mailosaur::Models::ServerCreateOptions.new()
options.name = 'Example'

mailosaur.servers.create(options)
$options = new ServerCreateOptions();
$options->name = 'Example';

$mailosaur->servers->create($options);
m.Servers.Create(&ServerCreateOptions{
  Name: "Example",
})
{
    "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.

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description
    The identifier of the server to be retrieved.
Postman iconInsomnia icon
GET /api/servers/:id
curl \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/servers/SERVER_ID
const server = await mailosaur.servers.get('SERVER_ID');
cy.mailosaurGetServer('SERVER_ID')
  .then(server => {
      cy.log(server.name); // "Example"
  });
server = mailosaur.servers.get("SERVER_ID")
Server server = mailosaur.servers().get("SERVER_ID");
var server = mailosaur.Servers.Get("SERVER_ID");
server = mailosaur.servers.get('SERVER_ID')
$server = $mailosaur->servers->get('SERVER_ID');
server := m.Servers.Get("SERVER_ID")
{
    "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.

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description
    The identifier of the server.
Postman iconInsomnia icon
GET /api/servers/:id/password
curl \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/servers/SERVER_ID/password
const password = await mailosaur.servers.getPassword('SERVER_ID');
cy.mailosaurGetServerPassword('SERVER_ID').then(password => {
  cy.log(password);
});
password = mailosaur.servers.get_password("SERVER_ID")
String password = mailosaur.servers().getPassword("SERVER_ID");
var password = mailosaur.Servers.GetPassword("SERVER_ID");
password = mailosaur.servers.get_password('SERVER_ID')
$password = $mailosaur->servers->getPassword('SERVER_ID');
password, err := m.Servers.GetPassword("SERVER_ID")
{
    "value": "server-password"
}

Update a server

Updates a single server and returns it.

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description
    The identifier of the server to be updated.

Body parameters

  • Name
    name
    Type
    string
    Required
    required
    Description
    The name of the server.
Postman iconInsomnia icon
PUT /api/servers/:id
curl \
  -X PUT \
  -H 'Content-Type: application/json' \
  -d '{"name":"Updated server name"}' \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/servers/SERVER_ID
await mailosaur.servers.update('SERVER_ID', {
  name: 'Updated server name'
});
cy.mailosaurUpdateServer('SERVER_ID', {
  name: 'Updated server name'
});
retrieved_server = mailosaur.servers.get("SERVER_ID")
retrieved_server.name = "Updated server name"

mailosaur.servers.update(retrieved_server.id, retrieved_server)
Server retrievedServer = mailosaur.servers().get("SERVER_ID");
retrievedServer.withName("Updated server name");

mailosaur.servers().update(retrievedServer.id(), retrievedServer);
var retrievedServer = mailosaur.Servers.Get("SERVER_ID");
retrievedServer.Name = "Updated server name";

mailosaur.Servers.Update(retrievedServer.Id, retrievedServer);
retrieved_server = mailosaur.servers.get("SERVER_ID")
retrieved_server.name = "Updated server name"

mailosaur.servers.update(retrieved_server.id, retrieved_server)
$retrievedServer = $mailosaur->servers->get('SERVER_ID');
$retrievedServer->name = 'Updated server name';

$mailosaur->servers->update($retrievedServer->id, $retrievedServer);
retrievedServer, err := m.Servers.Get("SERVER_ID")

if (err != nil) {
  // Handle err
}

retrievedServer.Name = "Updated server name"

m.Servers.Update(retrievedServer.Id, retrievedServer);
{
    "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.

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description
    The identifier of the server to be deleted.
Postman iconInsomnia icon
DELETE /api/servers/:id
curl \
  -X DELETE \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/servers/SERVER_ID
await mailosaur.servers.del('SERVER_ID');
cy.mailosaurDeleteServer('SERVER_ID');
mailosaur.servers.delete("SERVER_ID")
mailosaur.servers().delete("SERVER_ID");
mailosaur.Servers.Delete("SERVER_ID");
mailosaur.servers.delete('SERVER_ID')
$mailosaur->servers->delete('SERVER_ID');
m.Servers.Delete("SERVER_ID")

Usage

The Usage API allows you to view your account limits, as well as list usage history to better understand how your Mailosaur account is utilized.

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.

Postman iconInsomnia icon
GET /api/usage/limits
curl \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/usage/limits
const limits = await mailosaur.usage.limits();
cy.mailosaurGetSpamAnalysis().then(limits => {
  cy.log(limits)
})
limits = mailosaur.usage.limits()
UsageAccountLimits limits = mailosaur.usage().limits();
var limits = mailosaur.Usage.Limits();
limits = mailosaur.usage.limits()
$limits = $mailosaur->usage->limits();
limits, _ := m.Usage.Limits()
{
  "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.

Postman iconInsomnia icon
GET /api/usage/transactions
curl \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/usage/transactions
const limits = await mailosaur.usage.transactions();
cy.mailosaurGetSpamAnalysis().then(transactions => {
  cy.log(transactions)
})
limits = mailosaur.usage.transactions()
UsageTransactionListResult limits = mailosaur.usage().transactions();
var limits = mailosaur.Usage.Transactions();
limits = mailosaur.usage.transactions()
$limits = $mailosaur->usage->transactions();
limits, _ := m.Usage.Transactions()
{
  "items": [
    {
      "timestamp": "2021-01-31T00:00:00Z",
      "email": 2000,
      "sms": 51,
      "previews": 0
    }
  ]
}