Heroku

How It Works

Sendgrid

Last Updated: 08 February 2012

email sendgrid smtp

Table of Contents

Adding this add-on will instantly setup your Rails app to send emails using ActionMailer. Check the usage instructions below if you’re not using Rails or if you’re using another framework to send emails.

Sendgrid offers a modern, API driven approach to SMTP delivery. Currently there are several offers available for Heroku users: Sendgrid starter, a free alternative for apps sending up to 200 messages a day - and several paid plans, for apps with a high volume of emails.

Sendgrid Free

To enable free Sendgrid add-on, simply run:

$ heroku addons:add sendgrid:starter
Adding sendgrid:starter to myapp...done.

The basic account allows you to send up to 200 emails per day.

Increasing your outgoing email capability is equally simple. To activate one of the paid Sendgrid add-ons:

$ heroku addons:add sendgrid:bronze
Adding sendgridbronze to myapp...done.

Bronze will bump your limit to 40,000 emails per month. Other plans with more capacity are also available.

Usage

SendGrid requires you to setup the From: address when sending emails. Without it, their SMTP servers will throw exceptions.

If you’re not using Rails and ActionMailer, or you are using the Cedar stack, you will need to setup your email framework manually; check out examples below.

If your Rails app is using ActionMailer and running on the Aspen or Bamboo stack, Sendgrid will just work - no setup is needed after the add-on is installed.

ActionMailer

Note that a plugin to automatically configure ActionMailer for Rails is installed on our Aspen and Bamboo stacks. The following settings are necessary on Cedar, or for non-Rails apps using ActionMailer on Aspen or Bamboo.

config/initializers/mail.rb

ActionMailer::Base.smtp_settings = {
  :address        => 'smtp.sendgrid.net',
  :port           => '587',
  :authentication => :plain,
  :user_name      => ENV['SENDGRID_USERNAME'],
  :password       => ENV['SENDGRID_PASSWORD'],
  :domain         => 'heroku.com'
}
ActionMailer::Base.delivery_method = :smtp

Pony

We encourage developers to take a look at Pony for something simpler than ActionMailer, yet more convenient than net/smtp.

Pony.options = {
  :via => :smtp,
  :via_options => {
    :address => 'smtp.sendgrid.net',
    :port => '587',
    :domain => 'heroku.com',
    :user_name => ENV['SENDGRID_USERNAME'],
    :password => ENV['SENDGRID_PASSWORD'],
    :authentication => :plain,
    :enable_starttls_auto => true
  }
}

Mail

Mail.defaults do
  delivery_method :smtp, {
    :address => 'smtp.sendgrid.net',
    :port => '587',
    :domain => 'heroku.com',
    :user_name => ENV['SENDGRID_USERNAME'],
    :password => ENV['SENDGRID_PASSWORD'],
    :authentication => :plain,
    :enable_starttls_auto => true
  }
end

Other frameworks

Sendgrid has a large repository of examples for using Sendgrid across multiple languages and frameworks. If your framework is not listed below, we recommend checking out this page.

Generally speaking, any email framework supporting SMTP and plain authentication can be used with Sendgrid. Configure your email framework to use the server smtp.sendgrid.net and the appropriate port for your connection method, as follow:

  • 25 or 587 for TLS/plain connections
  • 465 for SSL connections

The SMTP username and password are stored in the ENV vars, as you can see in the examples above. To verify that the variables are set use the heroku config command.

Community Resources