stagingmail.md

stagingmail.md

Staging Mail is an add-on that provides an alternate SMTP server and mailbox for development and staging enviornments.

Adding Staging Mail to an application provides:

• A browser-based interface to previewing email sent by an application without clogging a personal mailbox.
• An easy way to forward messages to clients for approval or testing.
• Assurance that messages from test enviornments never reach production customers.

The Staging Mail addon supports any language, framework, or application that sends mail via SMTP.

Provisioning the add-on

Staging Mail can be attached to a Heroku application via the CLI:

:::term
$ heroku addons:add stagingmail
-----> Adding stagingmail to sharp-mountain-4005... done, v18 (free)

Once Staging Mail has been added a STAGINGMAIL_API_KEY and STAGINGMAIL_API_PASSWORD setting will be available in the app configuration. These are the credentials you'll use to authenticate with our SMTP server. This can be confirmed using the heroku config:get command.

:::term
$ heroku config:get STAGINGMAIL_API_KEY
app007@heroku.com

$ heroku config:get STAGINGMAIL_API_PASSWORD
qcCYE4dQTSzEnuxj3LH8

After installing Staging Mail add-on, configure the application to use Staging Mail's SMTP server.

Using with Rails

Ruby on Rails applications will need to add the following file to their application.

config/initializers/stagingmail.rb

:::ruby
unless Rails.env.production?
    ActionMailer::Base.smtp_settings = {
            :address        => 'smtp.stagingmail.com',
            :port           => '10587',
            :authentication => :plain,
            :user_name      => ENV['STAGINGMAIL_API_KEY'],
            :password       => ENV['STAGINGMAIL_API_PASSWORD'],
            :enable_starttls_auto => true
    }
    ActionMailer::Base.delivery_method = :smtp
end

This can also be done by running this command inside your application's root directory.

:::term
$ curl https://gist.github.com/raw/4525651/stagingmail.rb > config/initializers/stagingmail.rb

Using with Python/Django

Django applications will need to add the following file to their settings.py.

settings.py

:::python
EMAIL_HOST = 'smtp.sendgrid.net'
EMAIL_HOST_USER = 'ENV["STAGINGMAIL_API_KEY"]'
EMAIL_HOST_PASSWORD = 'ENV["STAGINGMAIL_API_PASSWORD"]'
EMAIL_PORT = 10587
EMAIL_USE_TLS = True

There are various ways to support Django applications with multiple environments, a good place to start is Django's Split Settings Wiki.

Local setup

Environment setup

It’s necessary to locally replicate the config vars if you'd like to your development environment to send emails to Staging Mail.

Though less portable it’s also possible to set local environment variables using `export STAGINGMAIL_API_KEY=value STAGINGMAIL_API_PASSWORD=value`.

Use Foreman to reliably configure and run the process formation specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the STAGINGMAIL_API_KEY and STAGINGMAIL_API_PASSWORD values retrieved from heroku config to .env.

:::term
$ heroku config -s | grep STAGINGMAIL_API_KEY >> .env
$ heroku config -s | grep STAGINGMAIL_API_PASSWORD >> .env
$ more .env
STAGINGMAIL_API_KEY=value
STAGINGMAIL_API_PASSWORD=value

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: `echo .env >> .gitignore`.

View Inbox

For more information on the features available within the Staging Mail dashboard please see the docs at [stagingmail.com/docs](stagingmail.com/docs).

The Staging Mail Inbox allows you to view incoming email messages, forward messages to another address, and create a sharable url for individual messages.

The inbox can be accessed via the CLI:

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

or by visiting the Heroku apps web interface and selecting the application in question. Select Staging Mail from the Add-ons menu.

Removing the add-on

Staging Mail can be removed via the CLI.

This will destroy all associated data and cannot be undone!

:::term
$ heroku addons:remove stagingmail
-----> Removing stagingmail from sharp-mountain-4005... done, v20 (free)

Support

All Staging Mail 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 howdy@stagingmail.com.