This add-on is operated by Dynamic Edge Software LTD

Scalable Incoming (and Transactional outbound) Email for your Heroku App

Last updated June 30, 2020

CloudMailin allows you to receive incoming email messages in your web app via an HTTP POST request.

When you install the CloudMailin Add-on you will be automatically given an email address to send email to. Any email sent to that address will automatically be forwarded to the web address of your choice.

Getting started receiving mail

To get started simply install the CloudMailin Add-on using the following command:

$ heroku addons:create cloudmailin

This will automatically create you a CloudMailin account and create an address that will forward to the default location.

You can also go ahead and specify the url that you want your email to be sent to, as you provision the addon, using the following option:

$ heroku addons:create cloudmailin --target https://yourapp.herokuapp.com/incoming_messages

As the addon is installed you will be shown the email address that CloudMailin has provisioned for you. This email address, along with your username and password are also available as configuration variables in the Heroku ENV vars, you can check the environment variables using the following:

$ heroku config

• CLOUDMAILIN_FORWARD_ADDRESS - The email address that was created for you to send messages to.
• CLOUDMAILIN_USERNAME - Used to allow you to log into the website manually.
• CLOUDMAILIN_PASSWORD - Used to allow you to log into the website manually.
• CLOUDMAILIN_SECRET (deprecated) - Was used to sign messages so that customers could ensure messages came from CloudMailin. We now recommend using HTTPS and basic auth.

At this point you’re ready to start sending email to your app. Remember, if you’re app hasn’t got any code to receive the message yet and returns a 404 status code the message will bounce (see HTTP status codes for more details).

Setting up your address

There are several ways to sign into CloudMailin and setup your email address. By default CloudMailin email addresses will forward to the CloudMailin 200 target. This location will simply return a 200 status code causing the server to believe the message has been accepted and do nothing else with it.

In order to forward your email to your own website and to setup other features you need login to the CloudMailin Dashboard. There are three different ways to do this:

Once logged in you can manage your CloudMailin email address.

HTTP POST message formats

Along with the target location you can also edit the format that CloudMailin uses to send your email as an HTTP POST to your app. CloudMailin offers 4 different message formats:

Adding your own domain

For the micro-plus and above plans you can specify your own domain name for all emails. CloudMailin also allows you to receive email for any subdomain of your domain too.

First you’ll have to add some DNS entries for your domain to receive the emails. More details can be found in the CloudMailin documentation. Once you’ve added the DNS records you’ll need to configure CloudMailin.

From the manage address page you can click the custom domain button. Adding your domain, such as yourdomain.com will allow you to receive any email address at your domain so *@yourdomain.com. If you added a wildcard DNS entry for your domain you can specify a wildcard in the domain such as *.yourdomain.com. This then allows you to receive any email at *@*.yourdomain.com. This is a great way to give your customers an easy to remember address such as create@customer.yourdomain.com.

Accepting or denying email

CloudMailin offers two additional callbacks to help you enhance your reliability and security.

The Authorization callback allows you to ensure that you’re happy with the sender and recipient of your email before the entire email is received. This is especially useful when you are using a custom domain to make sure that the list of recipients matches what you expect. For more details see the Authorization callbacks documentation. The authorization callback also includes the SPF status of the email, allowing you to check that the sender is allowed to send email for the given domain.

It’s also important to remember that the HTTP status code that your app passes will result in a different reply to the sending email server. If you specify a 2xx response code the message will be accepted, however 4xx status codes will bounce messages and 5xx status codes will cause them to be retried at a later date. More details are at HTTP Status Codes.

When these ‘error’ status codes occur you can also be notified. This allows you to instantly respond should your app have an error whilst receiving email. The details can be seen in the Error Callbacks documentation.

Attachments

Attachments can often be a complex aspect of Email. CloudMailin makes dealing with attachments simple. Our S3 attachments feature will allow you to send email directly to Amazons S3 and avoid any overhead in your app. However, if you want attachments to go straight to your app then you can do this too. The best format for this is the multipart format as attachments will simply be embedded in the request like normal file upload. However, they’re also available in the other formats too.

Adding your code

There are a number of examples within the documentation for the HTTP POST formats and some full (but often older) examples in the CloudMailin examples

Receiving email in Ruby

We’ll also add a Rails example here to show how easily you can get started. We recommend that customers use the multipart format by default:

class IncomingMailsController < ApplicationController
  skip_before_filter :verify_authenticity_token

  def create
    Rails.logger.log params[:envelope][:to] # print the to field to the logs
    Rails.logger.log params[:subject] # print the subject to the logs
    Rails.logger.log params[:plain] # print the decoded body plain to the logs if present
    Rails.logger.log params[:html] # print the html decoded body to the logs if present
    Rails.logger.log params[:attachments][0] if params[:attachments] # A tempfile attachment if attachments is populated

    # Do some other stuff with the mail message

    render :text => 'success', :status => 200 # a status of 404 would reject the mail
  end
end

However, it is possible to use the RAW format and parse the message yourself if needed:

class IncomingMailsController < ApplicationController
  require 'mail'
  skip_before_filter :verify_authenticity_token

  def create
    message = Mail.new(params[:message])
    Rails.logger.log message.subject #print the subject to the logs
    Rails.logger.log message.body.decoded #print the decoded body to the logs
    Rails.logger.log message.attachments.first.inspect #inspect the first attachment

    # Do some other stuff with the mail message

    render :text => 'success', :status => 200 # a status of 404 would reject the mail
  end
end

Notice the call to skip_before_filter :verify_authenticity_token to make sure that rails doesn’t raise an exception because we have no way of knowing the token.

Make sure your target is set to http://yourdomain.com/incoming_mails and thats it!

Additional resources

There are plenty more features to explore. More details and an FAQ can be found on the CloudMailin Docs Website. Good luck and feel free to contact us if you have any questions!