Mailosaur logo
Mailosaur logo
Dashboard

Home / Email and SMS Testing API

Messages

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

Last updated:

GET/api/messages/:id

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
    Description

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

Run in PostmanRun in Insomnia
Example request
curl \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/messages/MESSAGE_ID
Example response
{
    "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/api/messages/:id

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

Body parameters

  • Name
    id
    Type
    string
    Description

    The identifier of the message to be deleted.

Run in PostmanRun in Insomnia
Example request
curl \
  -X DELETE \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/messages/MESSAGE_ID
GET/api/messages?server=:server

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

Run in PostmanRun in Insomnia
Example request
curl \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/messages?server=SERVER_ID
Example response
[
    {
        "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/api/messages?server=:server

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
    Description

    The identifier of the server to be emptied.

Run in PostmanRun in Insomnia
Example request
curl \
  -X DELETE \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/messages?server=SERVER_ID
POST/api/messages/search?server=:server

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

Run in PostmanRun in Insomnia
Example request
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
Example response
[
    {
        "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": []
    }
]
POST/api/messages/:id/forward

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
    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
    Description

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

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

Run in PostmanRun in Insomnia
Example request
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
Example response
{
    "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"
}
POST /api/messages/:id/reply

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

Run in PostmanRun in Insomnia
Example request
curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"text":"Example"}' \
  -u api:YOUR_API_KEY \
  https://mailosaur.com/api/messages/MESSAGE_ID/reply
Example response
{
    "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"
}
POST /api/messages?server=:server

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.

Path parameters

  • Name
    server
    Type
    string
    Description

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

Body parameters

  • Name
    to
    Type
    string
    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
    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).

Run in PostmanRun in Insomnia
Example request
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
Example response
{
    "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"
}
Previous
Email and SMS Testing API
Next
Files