New and Improved SMTP Header REST API Endpoint

Devs and Quality Assurance Testers Can Easily Validate Mail Headers

The SMTP header endpoint provides quality assurance testers with the option to view an email message’s SMTP headers in parsed formats that easily integrate with automated testing frameworks.

Problem

Developers and QAs are often asked to validate contents of emails. This can include from address, links, and subject. For many organizations this can be a manual process of checking the email and validating if the test criteria has been met.

Solution

Mailsac’s new message header endpoint provides SMTP headers in 3 formats:

1. JSON object format, grouped by lowercased header key. This format is easily consumed by industry standard tools such as Selenium.

{
  "received": [
    "from 107.174.234.77 by frontend1-172-31-29-224 via 172.31.42.57 with HTTP id 8m7iqeiZKJ3MzwTwUQlU for <cd@mailsac.com>; Mon Dec 24 2018 15:29:06 GMT+0000 (Coordinated Universal Time)",
    "from 107.174.234.77 by smtp-in2-172-31-42-57 via 172.31.23.10 (proxy) with SMTP id 8m7iqeiZKJ3MzwTwUQlU for <cd@mailsac.com>; Mon, 24 Dec 2018 15:29:06 UTC",
  ],
  "from": [
    "grem@hello.msdc.co"
  ],
  "to": [
    "cd@mailsac.com"
  ],
  "subject": [
    "invitation to collaborate"
],
  "date": [
    "Mon, 24 Dec 2018 15:29:06 +0000"
  ]
}

2. Ordered JSON array format. This formats pre-parses the headers, but maintains the original order, while still handling duplicate headers such as Received.

?format=ordered-json

[
  {
    "name": "received",
    "value": "from 107.174.234.77 by frontend1-172-31-29-224 via 172.31.42.57 with HTTP id 8m7iqeiZKJ3MzwTwUQlU for <cd@mailsac.com>; Mon Dec 24 2018 15:29:06 GMT+0000 (Coordinated Universal Time)"
  },
  {
    "name": "received",
    "value": "from 107.174.234.77 by smtp-in2-172-31-42-57 via 172.31.23.10 (proxy) with SMTP id 8m7iqeiZKJ3MzwTwUQlU for <cd@mailsac.com>; Mon, 24 Dec 2018 15:29:06 UTC"
  },
...
  {
    "name": "to",
    "value": "cd@mailsac.com"
  },
]

3. Plaintext original format. This format is useful when you are interested in parsing or inspecting the email headers yourself, and do not wish to download the entire message.


?format=plain

Received: from 107.174.234.77 by frontend1-172-31-29-224 via 172.31.42.57 with HTTP id 8m7iqeiZKJ3MzwTwUQlU for <cd@mailsac.com>; Mon Dec 24 2018 15:29:06 GMT+0000 (Coordinated Universal Time)
Received: from 107.174.234.77 by smtp-in2-172-31-42-57 via 172.31.23.10 (proxy) with SMTP id 8m7iqeiZKJ3MzwTwUQlU for <cd@mailsac.com>; Mon, 24 Dec 2018 15:29:06 UTC
...
To: cd@mailsac.com

“We are currently using the REST API headers endpoint in support between our own microservices. Our POP3 server fetches headers of message to implement the POP3 TOP command.” — Michael Mayer, Partner Forking Software LLC

Getting Started

The message header endpoint /api/messages/:messageId/headers is available on all Mailsac plans (including our free tier). See our API Specification for more information.

This code example could can be modified to view the headers for the first email message on an inbox calendartrinity@mailsac.com. Make sure to insert your API Key and change the email address to an email address you which is public or reserved by your account.

const superagent = require('superagent') // npm install superagent

const mailsac_api_key = 'YOUR_API_KEY_HERE' // change this!

superagent
  .get('https://mailsac.com/api/addresses/calendartrinity@mailsac.com/messages')
  .set('Mailsac-Key', mailsac_api_key)
  .then((messages) => {
      const messageId = messages.body[0]._id
      superagent
          .get('https://mailsac.com/api/addresses/calendartrinity@mailsac.com/messages/' + messageId + '/headers')
          .set('Mailsac-Key', mailsac_api_key)
           .then((response) => {
               console.log(response.body)
           })
  })
  .catch(err => console.error(err))

/**
{
  received: [
    'from [ by fireroof via ::1 with HTTP id bo4xdVji_oqEixBO0gGLbvIoe for <calendartrinity@mailsac.com>; Wed, 28 Oct 2020 23:05:29 GMT',
    'from [ fireroof with SMTP id bo4xdVji_oqEixBO0gGLbvIoe for <calendartrinity@mailsac.com>; Wed, 28 Oct 2020 16:05:29 PDT'
  ],
  'x-mailsac-inbound-version': [ '' ],
  date: [ 'Wed, 28 Oct 2020 16:05:29 -0700' ],
  to: [ 'calendartrinity@mailsac.com' ],
  from: [ 'bclinton@mailsac.com' ],
  subject: [ 'test Wed, 28 Oct 2020 16:05:29 -0700' ],
  'message-id': [ '<20201028160528.2893005@fireroof>' ],
  'x-mailer': [ 'swaks v20190914.0 jetmore.org/john/code/swaks/' ]
}
**/

Multi-User Login using API Credentials, For Team Collaboration

Update: April 2021 – Multi-User login is now called “Sub-Accounts”

Named API Keys can now be used as website authentication.

Custom domains and Private Addresses have been great for quality assurance teams to conduct end to end automated testing of email. But sometimes interacting with an REST API can be a lot of overhead for non-repeating tasks. API Credentials can now be used to login to the website.

All private addresses and custom domains associated with the primary account will be visible from the website for API users. The permissions for API users are the same as API keys.

Quality assurance teams often share credentials of test accounts for the web application they are testing. These test accounts might to be associated with an email provisioned by their IT department or the QA tester’s personal email. Mailsac private domains allow the test accounts to be created in an an environment all members of the QA team have access to.

This feature allows teams to work together in the Mailsac platform. There is no longer a need to for each person to have their own Mailsac account. A named API Key can be created for each person. That API key can be used to interact with the REST API and the website. As a result, password resets and transaction emails sent to a Mailsac private domain can be accessed by any member of the QA team.

“Internally we have used Mailsac for collaboration. Being able to share a private address or domain allows my team members to see exactly what I am seeing. This feature allows our customers to do the same with their own private domains and addresses” Michael Mayer – Member – Forking Software LLC

Getting started is as easy as provisioning a new set of API credentials and enabling the website login on the API Key. This can be done the the Dashboard and selecting API Credentials & Users

Enable Website Login

We will be rolling this feature out to our Business and Enterprise Plans in the next couple weeks. If you have an immediate need for this feature we can enable it on your account. Contact support@team.mailsac.com to get early access to this feature on you Business or Enterprise Plan.

Retiring TLS 1.0 and TLS 1.1

Our REST APIs and website will require the use of TLSv1.2 on October 24, 2020. TLS 1.2 was published as RFC 5246 in 2008.

All major web browsers (Chrome, Edge, Internet Explorer, Firefox, and Safari) have already disabled TLS 1.0 and TLS 1.1. Most modern programming languages have support for TLS 1.2.

Integrations written in Java 6 and Python 2.6 do not have TLS 1.2 support.

References

Announcing the Email Capture Service

With email capture, Quality Assurance teams testing email delivery can easily see the exact emails customers will receive.

The new Email Capture Service is an SMTP server that accepts all mail regardless of the To and From address. It is similar to Mailsac’s existing disposable mail, with some key differences. The capture service acts like a fake outbound relay, rather than a fake inbound relay.

Messages sent via capture.mailsac.com are available for viewing from the Mailsac Website or REST API. This allows Quality Assurance teams to validate that the message was sent and the contents of the message.

Web applications frequently send transactional emails to users. During development and User Acceptance Testing, sending email is disabled in the application – so emails are not accidentally sent to customers or fake test addresses. Sending lots of bounces from a development application is a great way to get your domain blacklisted, greylisted, or onto a spam list.

Send via capture.mailsac.com instead

Web applications can be configured to use the Email Capture Service as their SMTP server. Emails sent by the application can then be viewed by developers and testers.

Customers have been sending test emails to hosted custom domains at Mailsac for years. The email capture services simplifies the process of sending emails to Mailsac by allowing developers to relay through Mailsac without any additional email infrastructure.

Michael Mayer – LLC Member at Forking Software LLC.

Most customers can get started sending through the Email Capture service instantly.
Wherever you input SMTP credentials in your application, change to the following:

  • Server Name: capture.mailsac.com
  • Port: 5587
  • Use Secure Connection: Yes (TLS)
  • User Authentication – Username: Mailsac account username *
  • User Authentication – Password: any Mailsac API Key for the account

Any email sent to the capture server will be available at the TO address in Mailsac’s UI or API.

* a private address or custom domain address may be used if your email library does not support a separate FROM address for the username.

Further Reading

REST Compliant Response From Email Validation API

The GET Method on the REST API endpoint /api/validations/addresses/:addressToValidate has been updated to return a JSON object. Previously, this endpoint was returning an array. The POST Method response remains unchanged.

An example GET request and response has been added to the Mailsac REST API documentation.

Email validation via the Mailsac Website is still available to all registered customers. An email address can be checked for valid format and if it is associated with any known disposable email services.

New Delete Messages Flag When Releasing a Private Email Address

When releasing a private address, there is now an option to “empty the inbox” – deleting all messages associated with the private address. You can find the option by clicking the settings button when managing your private addresses.

The API endpoint DELETE /api/addresses/:email now supports the query string deleteAddressMessages. When deleteAddressMessages=true is passed, all messages associated with the inbox will be deleted.

Please note that all messages are deleted, including starred/saved messages. It is immediate and irreversible.

Brand New Look To Dashboard

The Mailsac dashboard has a brand new look. Our commonly used services are easier discover. You may find out about features you never new existed.

Setting up disposable or test email for a domain has never been easier. With the Mailsac Zero-Setup-Subdomain, choose you subdomain name and start receiving emails within minutes.

We do our best to build simple, indispensable APIs and tools for Quality Assurance teams. End to end testing of emails sent by web applications is easy with Mailsac. API Keys are included with all Mailsac accounts, including our free tier with generous API call limits.

Increase your privacy by using the Mailsac’s free disposable email service. Send to virtually any @mailsac.com address and view the email without ever signing in. To see all messages in an inbox and to view images you will need to sign up for a free account. With the free account you can star messages you need to keep and make them hidden to other users. If you find yourself needing extra email addresses that nobody else can see. They are available as an addon.

Authentication Changes

Mailsac now requires authentication on all API routes and many parts of the website. The API key for your account can be created and viewed from the dashboard. If you are using the website to view emails you will need to create an account and sign in to view the body, images, and headers.

API Authentication

Many API routes required authentication prior to this change. If you are a customer with an existing API key and using it to make your API requests, there are no changes you need to make.

If you were using anonymous access, you will need to create an account and create an API key.

There are three methods for authenticating to the API. HTTP Header, Query String Parameter, and Request JSON Body. To use the HTTP Header create the request header Mailsac-Key and use the value of your API key. To use the query string parameter append the query string parameter _mailsacKey to the query section (after ?) in the url. Example: https://mailsac.com/api/addresses/test@example.com/messages?_mailsacKey=eoj1mn7x5y61w0egs25j6xrv
During a POST or PUT operation a JSON field _mailsacKey can be used.

For a complete list of API Routes check out the API documentation.

Website Authentication

The content of the most recent email received is still available without logging in. Older messages, images, and headers will require an account. You can register for an account for free.