API Documentation - MailSpons

Jump to section

General:

JSON:API
Authentication
Waiting for new emails

API's:

List inboxes
Clear entire inbox
Delete single message
List messages

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

attribute is the name of the attribute to perform the filter on. The list of filterable attributes can be found below in the "Response" section.
operator is the operation to perform. All comparisons are case sensitive. Can be one of the following:
- eq: Checks if the attribute is equal to the value.
- ne: Checks if the attribute is not equal to the value.
- in: Checks if the attribute is equal to one of the comma separated values.
- contains: Checks if the attribute contains the value.
- startswith: Checks if the attribute starts with the value.
- endswith: Checks if the attribute ends with the value.
value is the value to compare against.

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"
          }
        ]
      }
    }
  ]
}

Links:

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.

JSON REST API documentation

Jump to section

JSON:API

Authentication

Waiting for new emails

Example

List inboxes

Request

Response

Example:

Attributes:

Clear entire inbox

Request

Parameters:

Example:

Response

Delete single message

Request

Parameters:

Example:

Response

List messages

Request

Parameters:

Filters

Examples:

Response

Example:

Links:

Attributes:

Download email message

Fetch attachments

Navigation

Contact