Mailtrap

Table of Contents [expand]

Provisioning the add-on
Local setup
Using with Rails 3.x-8.x
Using with Django
Tutorials
Dashboard
Removing the add-on
Support

Last updated October 23, 2025

This add-on is operated by Railsware Products Studio LLC

Modern Email Delivery for developer & product teams

Mailtrap is an email platform designed for developer and product teams looking for high inboxing rates, fast delivery, and industry-best analytics.

We offer flexible RESTful API and SMTP service for sending transactional and bulk emails, as well as an Email Sandbox to inspect and debug emails with no risk of spamming customers’ inboxes.

The Email Sandbox add-on for Heroku gives you access to a safe email testing environment. It implements a dummy SMTP server that catches your emails from development, staging, and QA environments, displaying them in a virtual sandbox. With the Email Sandbox add-on, your development team can easily:

Inspect and debug emails in a secure sandbox without spamming real customers.
Preview and analyze email content (HTML, text, and raw)
Validate HTML/CSS and get a list of possible errors across popular email clients
Check whether personalization works as designed and headers are correct (on the advanced plans, you can also test Bcc in emails)
Make sure that links work properly
Get spam and domain blocklisting reports
Automate your email testing workflows
Forward your test emails to regular recipients and monitor your production server (on the advanced plans)
Report easily on your progress by sharing your email testing results (on the advanced plans)
Organize your email testing data with inboxes and projects

Provisioning the add-on

You can integrate Email Sandbox with a Heroku application via the CLI:

$ heroku addons:create mailtrap
-----> Adding mailtrap to sharp-mountain-4005... done, v18 (free)

Api Token will be available in the app configuration. Using your API token, you can get the credentials used to access the newly provisioned service Mailtrap instance, MAILTRAP_API_TOKEN. This can be done in the following way.

require 'rest-client'
require 'json'

response = RestClient.get(
  'https://mailtrap.io/api/v1/inboxes.json',
  { Authorization: "Bearer #{ENV.fetch('MAILTRAP_API_TOKEN')}"}
)

ActionMailer::Base.delivery_method = :smtp
ActionMailer::Base.smtp_settings = {
  :user_name => first_inbox['username'],
  :password => first_inbox['password'],
  :address => first_inbox['domain'],
  :domain => first_inbox['domain'],
  :port => first_inbox['smtp_ports'][0],
  :authentication => :plain
}

For more information, please refer to mailtrap.docs.apiary.io. After installing Mailtrap, the application should be configured to fully integrate with the add-on.

Local setup

After provisioning the add-on, it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Though less portable, it’s also possible to set local environment variables using the export command locally.

Use the Heroku Local command-line tool to configure, run, and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from a .env file. To view all of your app’s config vars, type heroku config. Use the following command to add the MAILTRAP values retrieved from heroku config to your .env file.

$ heroku config -s | grep MAILTRAP >> .env
$ more .env

For more information, see the Heroku Local article.

Using with Rails 3.x-8.x

In config/environments/*.rb specify ActionMailer defaults:

require 'rubygems' if RUBY_VERSION < '1.9'
require 'rest-client'
require 'json'

response = RestClient.get(
  'https://mailtrap.io/api/v1/inboxes.json',
  { Authorization: "Bearer #{ENV.fetch('MAILTRAP_API_TOKEN')}"}
)

first_inbox = JSON.parse(response)[0] # get first inbox

ActionMailer::Base.delivery_method = :smtp
ActionMailer::Base.smtp_settings = {
  :user_name => first_inbox['username'],
  :password => first_inbox['password'],
  :address => first_inbox['domain'],
  :domain => first_inbox['domain'],
  :port => first_inbox['smtp_ports'][0],
  :authentication => :plain
}

Using with Django

Add the following to settings.py

import requests

headers = {
    "Authorization": "Bearer <MAILTRAP_API_TOKEN>",
}
response = requests.get("https://mailtrap.io/api/v1/inboxes.json", headers=headers)
credentials = response.json()[0]

EMAIL_HOST = credentials['domain']
EMAIL_HOST_USER = credentials['username']
EMAIL_HOST_PASSWORD = credentials['password']
EMAIL_PORT = credentials['smtp_ports'][0]
EMAIL_USE_TLS = True

Tutorials

Mailtrap has a tech support team of engineers and deliverability experts who can assist you with any issue via email support[at]mailtrap.io or live chat in-app. Urgent cases are addressed immediately.

They also have a host of documentation and guides:

Dashboard

You can access the dashboard via the CLI:

$ heroku addons:open mailtrap
Opening mailtrap for sharp-mountain-4005…

or by visiting the Heroku Dashboard and select Mailtrap from the Add-ons menu.

Removing the add-on

Email Sandbox can be removed via the CLI.

$ heroku addons:destroy mailtrap
-----> Removing mailtrap from sharp-mountain-4005... done, v20 (free)

Support

All Mailtrap support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support-related issues or product feedback is welcome at support@mailtrap.io

Categories