Spring Cleaning with Mailsac API

My garden has been planted and the days are getting warmer. Next task, cleaning up. Mailsac won’t help you organize you garage or avoid the accumulation of clutter. But it can help you get rid of old emails.

The Delete All Messages in a Domain Endpoint released on March 23, 2021 can help you keep your private domain storage under the storage limit. It’s useful for deleting all messages before running integration tests.

This post will detail the different methods of bulk message deletion.

Cleanup a Custom Domain

All messages in a custom domain can irrevocably be deleted.

From the Dashboard select Custom Domains Select Domain to Mange → Advanced tab → Irreversibly Delete Email

The REST API has a commensurate endpoint for deleting all messages in a domain. It can be invoked by calling an HTTP POST https://mailsac.com/api/domains/{domain}/delete-all-domain-mail , where {domain} is the custom domain.

Cleanup a Private Inbox

All messages in a Private Inbox can be deleted from the website or the REST API. Both methods will not delete starred messages.

From the From the Dashboard select Manage Email Addresses Select Email Address Purge Inbox

Messages in a Private Inbox can be deleted using the endpoint for deleting messages in a private inbox. The endpoint can be used with the HTTP DELETE method on https://mailsac.com/api/addresses/{email}/messages where {email} is the private email address.

Deleting Individual Messages

Individual messages can be deleted from both private and non-private inboxes.

From the From the Dashboard enter an inbox in the inbox viewer form and select Check The Mail!. From the Inbox, Click the message → Select Delete Permanently Delete

Individual messages can be deleted using the delete message REST API. The endpoint can be called using an HTTP DELETE with the URL https://mailsac.com/api/addresses/{email}/messages/{messageId} . The {email} parameter is the email address and the {messageId} is identifier for the message to be deleted. The messageId can be found by using the list messages in an inbox REST API endpoint.

Improved SMTP Relay Logs

The Recent Activity Log now includes detailed sender and delivery information for outbound email. This empowers customers to diagnose sending issues.

Successful Email Log Entry

The screenshot below shows a successful email delivery sent from user2@mailsac.com to user1@mailsac.com. The email message id, number of delivery attempts, rejection status, and time stamps are included in the logs

Failed Email Log Entry

The screenshot below shows a failed email delivery from somebody@mailsac.com. The message id, number of attempts, timestamp, and error message are provided.

This error message indicates that the recipients domain no-where-no-where-no-where.info does not exist.

Industry Standard API Documentation

Mailsac API Documentation has been converted over to use OpenAPI.

Code Examples

The new format gives developers and quality assurance testers code samples for common programming languages (curl, Node, Python, PHP, Go, etc).

Explore the API Using Swagger UI

The API can be explored without writing any code using the Swagger UI Explorer. All that is needed to get started is a free Mailsac API Key (requires sign up).

In the Swagger UI Explorer, choose the Authorize button and enter your Mailsac API Key


Use the “Try it out” button to interact with any of the REST API endpoints. A curl example, request URL, response body, and headers are provided.

New Features Available On All Plans

All of our plans now included additional features. These features will help quality assurance teams and individual developers test sending and receiving of email, and easily share non-production email accounts.

To see a complete listing of feature visit see our pricing page.

We are in the process of rolling out these features to our existing customers. Please contact support@team.mailsac.com if you need access to the features ahead of our scheduled roll out.

Free Plan

Old PlanNew Plan Feature / Limit
N/AEmail Capture
N/AWebhook Forwarding (requires private inbox)
N/AWebSocket Forwarding (requires private inbox)
N/APurge Inbox (requires private inbox)
N/ASlack Webhooks (requires private inbox)
N/ACommunity Support

Indie Plan

Old PlanNew Plan Feature / Limit
10 Private Addresses50 Private Addresses
0 Outgoing Messages500 Outgoing Messages (non-recurring)
N/AEmail Capture
N/AMessage Logs (15 minutes)
N/ADelete all messages by domain

Business Plan

Old PlanNew Plan Feature / Limit
50 Private Addresses250 Private Addresses
0 Outgoing Messages2,500 Outgoing Messages (non-recurring)
N/AWebsite Login using API Key (2 users)
N/AMessage Logs (1 month)

Enterprise Plan (New Plan)

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/' ]
}
**/

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.

Slack Webhook Integration with Private Email Addresses

Last year, we soft-launched a new forwarding feature on private addresses. You may have noticed – underneath the “Forwarding” section, there is now a Forward to Slack option. (Manage Addresses > Settings > Forwarding)

With only a little clicking, you can have inbound emails dumped into a Slack channel. It’s easy – no coding, and no servers, are necessary.

We built this feature because we use Slack internally, and had a custom webhook translator to send certain emails to a channel. After a little copy and paste, code massaging, and unit testing, we were able to get the feature into the platform.

Email → Slack Options

After inserting a valid Slack Webhook URL, we give you the option to enable the To and From address to display in the Slack message (Include To and From in the slack message checkbox).
Here’s the difference:

Screenshot from slack receiving an email from Mailsac
Disabled TO and FROM in Slack Message
Enabled FROM and TO in Slack Message from Email

Enabling TO and FROM is useful for support requests, shared email inboxes, or when you might have multiple inboxes pointed at the same channel.

Disabling TO and FROM is useful for receiving alerts or notifications from the same service. For example, if you send a notification about a new purchase on your website to a Slack channel, and it always comes from the same service email address, you don’t need it to take up space in the Slack message.

Email Images and Attachments to Slack

The email-to-Slack forwarding feature supports file attachments, including images. Images will be displayed inline.

We recommend archiving attachments outside Slack at this time. Attachments are subject to recycling. Also, attachments must be made public in order for Slack to accept the messages. So do not send any PII or sensitive information. This is another reason why we chose to recycle attachments.

The same Mailsac message size limits apply for Slack. If you are interested in bumping up the attachment sizes, make a feature request or contact support and include your account ID.

Debugging Forwarding

The mail activity log will show forwards, and reports failures posting to Slack with error messages. (Dashboard / Usage / Recent Mail Activity Log)

Debug logging on email webhooks to Slack. Response data is redacted.
On errors, you will see Slack’s response.

Feedback

As always, please post feedback and questions to the Mailsac Discussion Forum. We think the feature is useful as-is, but we are open to making changes to better meet our customers needs.

Read more about the email-to-Slack webhook on our docs site.