This add-on is operated by Dynamic Edge Software Ltd
Scalable Incoming Email for your Heroku App
Last updated 07 May 2015
Table of Contents
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 privision 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:
|Using the Terminal||Use the toolbelt and enter
|Using the Heroku Website||Just login to Heroku and select CloudMailin from the Add-On menu for your application.|
|Using a Username and Password||First, obtain your CloudMailin Username and Password using
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:
||details||Exactly the same as the
||details||The original CloudMailin message format. This is stable and battle hardened.|
||details||This sends just original Raw message as a single
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
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 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.
Receiving email in Ruby
There are plenty of examples in the CloudMailin documentation however, we’ll include a Rails 3 example here to give an overview:
With Rails 3 you can either use the RAW format like so:
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
However, it’s probably easiest now to use the multipart format:
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] 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
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!
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!