November 25, 2010 4 Comments
In this post, we’re going to take a step by step guide approach to configuring and receiving your first email in you web app with CloudMailin. CloudMailin allows you to receive email in your web app via an HTTP POST. You setup the server to point to your site’s public url and your email is sent straight to the site. We will also cover how to add your own domain name and set it up so that you can give customers your own email address.
As soon as you sign up, you will be presented with the option to create your CloudMailin address. Here you enter the url of page that you wish to receive your email via HTTP Post at. After you click submit, an email address will be generated for you and anything you send to that email address will be sent to your website.
Once you click the submit button, the site will generate your email address and you will be ready to go. You will be redirected to the address list page. Here you can see each of your CloudMailin addresses, the target, that your HTTP Post will be sent to when an email is received and the plan details. Each CloudMailin address sits in its own plan so you can have different allocations for each address and therefore web app you want to receive email within. Currently the site is in beta so there is only one free plan. However once the site launches, there should always be a free plan to get started.
If you click on the address listed in the address list, you are taken to the page for that address. On this page are a number of configuration options for the address but also the delivery status list. The delivery status list is a powerful feature that allows you to see each email that passes through the system and the status of that message.
So lets go ahead and send an email to the address that CloudMailin has given us. We should almost instantly get a response back saying that the message delivery has failed.
What? The delivery failed? When we take a look at the delivery status page we can not only see that the message has failed but see that the target gave a status code of 404 because we never set up a page to receive the email. CloudMailin is clever enough to know the difference between the status codes that it receives when it delivers the email. If it receives a status code like 200 it assumes that everything was ok and the message was received successfully. If the target server has an error then or is unavailable then CloudMailin will tell the server that an error has occurred and that it should retry later. Finally if a status code like 404 or 422 occurs then it will tell the server that the message was rejected and that it should not try again later. More details about the HTTP responses that you can give to CloudMailin and the actions taken can be found in the HTTP status codes documentation. You can even send a custom bounce message when you reject the delivery of an email so long as your response is in plain text.
Ok so now its time to write some code and receive our email. If you are using Rails, you can take a look at some previous blog posts. There are also some examples in the parsing the email documentation. CloudMailin is language agnostic though, you can use it to receive incoming email in Java, PHP, Python, .Net, Scala, Small Talk or any other language that you want (so long as it can parse HTTP Posts). We are hoping to expand the languages in the documentation and they are all on github so feel free to contribute documentation for your favorite language! The request is sent to your server in the same way as any other form that you would fill in on your site as a multipart/form-data request. The plaintext and html parts are also nicely separated out to make life easier but the full email is available to allow more detail and attachments if it’s needed. The HTTP Post format documentation should help here.
Great, so now we have our server configured correctly, we’re ready to receive our email. So lets go ahead and send another email to our CloudMailin email address.
Awesome, Green lights! So now we’re successfully receiving our emails and processing the contents. What else can we do? Well, if you take a look down the right hand side of our address page, there’s a button labeled custom domains. This allows us to use our own domain name to receive email with whatever address we want. In order to do this though we need to start by configuring our DNS server to point any emails sent to our domain to the CloudMailin server. The documentation has a page dedicated to showing you how to configure your DNS server’s MX records to point to the CloudMailin servers and allow you to receive email via your own domain.
Once we have configured our DNS records we can go ahead and add our domain name to the custom domains form that we can open using the custom domains button. If you want to create client subdomains like email@example.com and firstname.lastname@example.org you can also add subdomains.
So that’s it. Using CloudMailin we can pretty easily receive email in our web apps. We’d love to hear what you create and also remember all of the documentation is on Github so if you have changes or additions or importantly examples for other programming languages and frameworks then please fork the documents and send a pull request. Most importantly feedback is always appreciated.