Mailosaur

Messages

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

Retrieve a message

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.

Parameters

Path parameters

id string

The identifier of the message to be retrieved. This can be found via other API calls such as List/Search.

Code samples

Run in Postman Run in Insomnia

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 := m.Messages.GetById("MESSAGE_ID")
Response
Status: 200
{
    "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.

Parameters

Body parameters

id string

The identifier of the message to be deleted.

Code samples

Run in Postman Run in Insomnia

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")
Response
Status: 204

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.

Parameters

Query parameters

server string

The identifier of the server hosting the messages.

receivedAfter datetime

Limits results to only messages received after this date/time.

page integer

Used in conjunction with itemsPerPage to support pagination.

itemsPerPage integer

A limit on the number of results to be returned per page. Can be set between 1 and 1000 items, the default is 50.

dir string

Optionally limits results based on the direction (Sent or Received), with the default being Received.

Code samples

Run in Postman Run in Insomnia

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"
Response
Status: 200
[
    {
        "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.

Parameters

Query parameters

server string

The identifier of the server to be emptied.

Code samples

Run in Postman Run in Insomnia

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")
Response
Status: 204

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.

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.

Parameters

Query parameters

server string

The identifier of the server hosting the messages.

receivedAfter datetime

Limits results to only messages received after this date/time.

page integer

Used in conjunction with itemsPerPage to support pagination.

itemsPerPage integer

A limit on the number of results to be returned per page. Can be set between 1 and 1000 items, the default is 50.

dir string

Optionally limits results based on the direction (Sent or Received), with the default being Received.

Body parameters

sentFrom string

The full email address or phone number from which the target message was sent.

sentTo string

The full email address or phone number to which the target message was sent.

subject string

The value to seek within the target email’s subject line.

body string

The value to seek within the target message’s HTML or text body.

match string

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.

Code samples

Run in Postman Run in Insomnia

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)
Response
Status: 200
[
    {
        "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.

Parameters

Path parameters

id string

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

Body parameters

to string

The verified external email address to which the message should be sent.

html string

Any HTML content to prefix the forwarded message with.

text string

Any plain text content to prefix the forwarded message with.

Code samples

Run in Postman Run in Insomnia

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>",
})
Response
Status: 200
{
    "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.

Parameters

Path parameters

id string

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

Body parameters

html string

Any HTML content to prefix the reply with.

text string

Any plain text content to prefix the reply with.

attachments array of objects

An object array of base64-encoded attachment objects (fileName, contentType, content).

Code samples

Run in Postman Run in Insomnia

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>",
})
Response
Status: 200
{
    "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.

Parameters

Path parameters

server string

The identifier of the server from which the email should be sent.

Body parameters

to string

The verified external email address to which the email should be sent.

from string

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.

html string

HTML content for the email.

text string

Plain text content for the email.

send boolean

If not true, then the email will be created in your server, but will not be sent.

attachments array of objects

An object array of base64-encoded attachment objects (fileName, contentType, content).

Code samples

Run in Postman Run in Insomnia

POST
/api/messages?server=:server
curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"to":"someone@example.com","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,
})
Response
Status: 200
{
    "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"
}