MailSpons

JSON REST API documentation

Jump to section

General:

API's:

JSON:API

The MailSpons API implements the JSON:API specification. This is beneficial for both us and our users.

It saves us from having to write custom MailSpons client library for each programming language and framework. You can simply use one of the many already existing, battle tested, JSON:API compliant client libraries.

If you don't want to use a third-party client library, that's ok too! The JSON schema is very straightforward.

JSON:API uses application/vnd.api+json instead of application/json as its MIME Content-type.

Authentication

You'll need to have a MailSpons account set up from here on. You can register for free.

Authentication is done using HTTP Basic Auth. You must authenticate every API call with your MailSpons email address and password. As of yet, there is no way to create real API keys. If you don't want to use your personal login credentials for API requests, you can invite a fake member into your MailSpons team and designate that account as the "API user".

Please keep in mind that, permission wise, there is no distinction between UI and API access. That means: everything a user can do through the web-interface the same user can also do through (future) API's. Do not store your API credentials in version control, client-side code, etc.

Waiting for new emails

There are cases when you want to wait for an email matching certain criteria. One example would be: running end-to-end tests using Selenium, Cypress or [enter favorite framework here].

Instead of repeatedly polling the API, you can append &waitForResults=n to the request url. This stalls the HTTP request until at least n results have been found. The request is stalled up to 30 seconds. After the timeout expires and there are still not enough matches, the request responds with a 307 Temporary Redirect back to itself. This happens up to 10 times, which is equivalent to around 5 minutes. If, after the last request there still aren't enough results, whatever is available will be returned.

Hint: Make sure your HTTP client is configured to follow redirections.

Example

The following request waits for at least one message to arrive with the phrase "confirm email" in its subject:

GET https://api.mailspons.com/api/v1/inboxes/1234/messages?filter[subject][contains]=confirm+email&waitForResults=1

List inboxes

List all inboxes accessible to the authenticated user.

Request

GET https://api.mailspons.com/api/v1/inboxes

No additional parameters are available.

Response

Always returns a 200 OK response.

Example:

{
  "data": [
    {
      "type": "inbox",
      "id": "1234",
      "attributes": {
        "teamId": "1",
        "name": "My first inbox",
        "emailAddress": "935a378b99134e96a6fc@mailspons.com",
        "smtpHost": "smtp.mailspons.com",
        "smtpUsername": "935a378b99134e96a6fc",
        "smtpPassword": "229d1e277b7847689e69369190dae7e3",
        "popHost": "pop.mailspons.com",
        "popUsername": "935a378b99134e96a6fc",
        "popPassword": "229d1e277b7847689e69369190dae7e3"
      }
    }
  ]
}

Attributes:

Name Description
teamId ID of the team the inbox belongs to.
name Name of the inbox.
emailAddress Public email address of the inbox. You can send emails to this address using any mail provider. It's just a regular email address.
smtpHost SMTP domain name to configure in your application. Available ports are: 25, 587, 2525 (STARTTLS/cleartext) or 465 (Implicit TLS).
smtpUsername SMTP user name.
smtpPassword SMTP password.
popHost POP3 domain name. Available ports are: 110 (STARTTLS/cleartext) or 995 (Implicit TLS).
popUsername POP3 user name.
popPassword POP3 password.

Clear entire inbox

Empty an inbox by removing all messages.

Request

DELETE https://api.mailspons.com/api/v1/inboxes/{inbox}/messages

Parameters:

Name Description
{inbox} Required. ID of the inbox to clear.

Example:

DELETE https://api.mailspons.com/api/v1/inboxes/1234/messages

Response

On success: returns an empty 204 No Content response.

If the inbox was not found a 404 Not Found response will be returned.

Delete single message

Remove one message.

Request

DELETE https://api.mailspons.com/api/v1/messages/{message}

Parameters:

Name Description
{message} Required. ID of the message to delete.

Example:

DELETE https://api.mailspons.com/api/v1/messages/567

Response

On success: returns an empty 204 No Content response.

If the inbox was not found a 404 Not Found response will be returned.

List messages

Find messages in an inbox.

Request

GET https://api.mailspons.com/api/v1/inboxes/{inbox}/messages

Parameters:

Name Description
{inbox} Required. ID of the inbox.
filter Filter the results. See below.
waitForResults Instructs the API to wait for at least n results. See the Waiting for new emails section above for more information.

Filters

Filters take the form of:

filter[attribute][operator]=value

Examples:

Get all messages in an inbox:

GET https://api.mailspons.com/api/v1/inboxes/1234/messages

Find all messages sent by "john@example.com":

GET https://api.mailspons.com/api/v1/inboxes/1234/messages?filter[sender.email][eq]=john%40example.com

Find all messages sent by "john@example.com", "jane@example.com" or "acme@example.com":

GET https://api.mailspons.com/api/v1/inboxes/1234/messages?filter[sender.email][in]=john%40example.com,jane%40example.com,acme%40example.com

Find all messages where "jane@example.com" is one of the main recipients:

GET https://api.mailspons.com/api/v1/inboxes/1234/messages?filter[to.*.email][eq]=jane%40example.com

Get all messages sent to any "@example.com" address:

GET https://api.mailspons.com/api/v1/inboxes/1234/messages?filter[to.*.email][endswith]=%40example.com

Get all messages sent to any "@example.com" address, except "blacklist@example.com":

GET https://api.mailspons.com/api/v1/inboxes/1234/messages?filter[to.*.email][endswith]=%40example.com&filter[to.*.email][ne]=blacklist%40example.com

Wait for at least one message to arrive with the phrase "confirm email" in its subject:

GET https://api.mailspons.com/api/v1/inboxes/1234/messages?filter[subject][contains]=confirm+email&waitForResults=1

Response

Returns a 200 OK response or possibly a 307 Temporary Redirect if the waitForResults parameter was set. (See the Waiting for new emails section.)

Example:

{
  "data": [
    {
      "type": "message",
      "id": "567",
      "links": {
        "self": "https://api.mailspons.com/api/v1/messages/567",
        "raw": "https://api.mailspons.com/api/v1/messages/567.eml",
        "text": "https://api.mailspons.com/api/v1/messages/567.txt",
        "html": "https://api.mailspons.com/api/v1/messages/567.html"
      },
      "attributes": {
        "inboxId": "1234",
        "receivedAt": "2020-01-02T03:04:05.67890",
        "receivedFromIP": "127.0.0.1",
        "receivedOnPort": 25,
        "origin": "authenticated_smtp",
        "transportSecurity": "starttls",
        "transportSecurityProtocol": "tls1.2",
        "blockedByChaosMode": false,
        "size": 12345,
        "mimeMessageId": "b225f85f-8784-408f-a2c0-40e65727f79e@example.com",
        "subject": "Welcome to MailSpons!",
        "sentAt": "2020-01-02T03:04:05+02:00",
        "sender": {
          "email": "welcome@mailspons.com",
          "name": "MailSpons welcoming committee"
        },
        "from": [
          {
            "email": "welcome@mailspons.com",
            "name": "MailSpons welcoming committee"
          }
        ],
        "to": [
          {
            "email": "user@example.com",
            "name": null
          }
        ],
        "cc": [],
        "bcc": [],
        "replyTo": [],
        "helo": "mail.mailspons.com",
        "mailFrom": {
          "email": "welcome@mailspons.com",
          "name": null
        },
        "rcptTo": [
          {
            "email": "user@example.com",
            "name": null
          }
        ],
        "attachments": [
          {
            "size": 123456,
            "filename": "contract.pdf",
            "contentType": "application/pdf",
            "contentDisposition": "attachment",
            "downloadLink": "https://api.mailspons.com/api/v1/attachments/987/download"
          }
        ],
        "htmlLinks": [
          {
            "href": "https://en.wikipedia.org/wiki/Special:Random",
            "text": "Random facts!",
            "testAttribute": "random-article-link"
          }
        ]
      }
    }
  ]
}
Name Description
self Message resource itself. As of yet only supports the DELETE method.
raw Download the raw message as a .eml file.
text Download the plain text part of the message as a .txt file. If the message has no text part, this link will be absent.
html Download the HTML part of the message as a .html file. If the message has no HTML part, this link will be absent.

File downloads must also be authenticated, just like regular API requests.

Attributes:

Name Description
inboxId ID of the inbox this message is in.
receivedAt ISO 8601 UTC timestamp including milliseconds of the moment the MailSpons SMTP server received the message.
receivedFromIP IP address of the host which delivered the message.
receivedOnPort Which TCP port was used to deliver the message.
origin Method used to deliver the message. Can be "authenticated_smtp" or "public_email_address".
transportSecurity Method used to encrypt the communication channel. Can be null, "starttls" or "implicit_tls".
transportSecurityProtocol Security protocol used. Can be "none", "tls1.0", "tls1.1", "tls1.2".
blockedByChaosMode Whether the message was blocked by Chaos Mode. (Configurable in the inbox settings.) When Chaos Mode "blocks" a message, MailSpons does store the message, but returns an error to the SMTP client making it think delivery has failed.
size Total size of the message in bytes.
mimeMessageId Filterable. Message ID as found in the Message-ID MIME header.
subject Filterable. Subject of the message.
sentAt ISO 8601 timestamp including timezone offset. This value is parsed from the Date header.
sender.email Filterable. Sender of the email. If the message does not explicitly define a Sender header, the From address will be used as sender.

From is who the message is from. It is who the recipient's email client should display the message is from.
Sender is usually the same as From, unless the message was originated by somebody, or some other system than the actual From address.

For example: Gmail when it's configured for a domain not hosted by Gmail. The From would contain you@yourdomain.com, but the Sender will contain someone@gmail.com. Many mail clients will render this as someone@gmail.com on behalf of you@yourdomain.com.
Another example would be a user sending email on behalf of another user - e.g. a secretary sending on behalf of an executive.

For most purposes you should probably be using the sender.email instead of the from.*.email atttribute.
sender.name Name of the sender.
from.*.email Filterable. From email. See documentation for sender.email.
from.*.name From name.
to.*.email Filterable. To email.
to.*.name To name.
cc.*.email Filterable. CC email.
cc.*.name CC name.
bcc.*.email Filterable. BCC emails as specified by the BCC MIME header. BCC's are a bit unusual, because they are meant NOT to be seen anywhere. Normally, the email client transforms any BCC addresses to additional rcptTo addresses and so this bcc.*.email attribute will be empty. If the final MIME message contains the blind carbon copies, they wouldn't be blind anymore.

For most common day use: take all rcptTo addresses, subtract all to, cc and bcc addresses. What you end up with is a guesstimate of the "real" BCCs.
bcc.*.name BCC name.
replyTo.*.email Filterable. Reply to email.
replyTo.*.name Reply to name.
helo Filterable. The HELO/EHLO greeting from the SMTP conversation.
mailFrom.email Filterable. MAILFROM of the SMTP envelope. Also known as "return path" or "bounce address", "envelope from", "reverse path", "errors-to".
mailFrom.name At the time of writing: always null.
rcptTo.*.email Filterable. RCPT TO's of the SMTP envelope.
rcptTo.*.name At the time of writing: always null.
attachments.*.size File size of the attachment in bytes.
attachments.*.filename File name of the attachment.
attachments.*.contentType MIME Content-Type of the attachment.
attachments.*.contentDisposition "inline" means that it should be automatically displayed when the message is opened. Typically used for embedded HTML images. Some email clients do not present a "Download"/"Save" action for inline attachments.
"attachment" means it should not be displayed automatically and requires some form of action from the user to open it. Regular attachment.
attachments.*.downloadLink Download location. File downloads must be authenticated, just like regular API requests.
htmlLinks.*.href Link destination.
htmlLinks.*.text Text inside the <a>...</a> tag.
htmlLinks.*.testAttribute If present: value of one of the following HTML attributes on the anchor tag:
data-test
data-testid
data-test-id
data-cy

Download email message

To download the entire MIME message or only the HTML or plaintext part: see the documentation for the raw, html and text links above.

Fetch attachments

To download an email attachment: see the documentation for attachments.*.downloadLink above.