Introduction

Mailgun is a web service that provides virtual email servers in the cloud. It is a reliable transport infrastructure that allows developers to build apps that send, receive and forward email in real time using our REST API. We support SMTP too: developers can start sending via Mailgun leveraging their existing SMTP setup by changing a few configuration settings.

The major functions of Mailgun are laid out below.

Functionality

Mailgun lets you sign up for your own virtual email server. The process is similar to signing up for a virtual server (or instance) from VPS hosting providers such as Amazon and Rackspace. Upon sign up, you will be directed to the Mailgun control panel where you can pick up your API key and SMTP login credentials, view live message logs, analyze stats, and more. You will be able to pick a domain name for your email server (or use the Mailgun-provided one), configure DNS, and start sending and receiving messages immediately.

Sending email

You can send messages from within your code by performing an HTTP POST to the Mailgun API or via SMTP. All messages will appear as if it were sent directly from your domain, using your own dedicated IP address. Here is a code sample showing how to send an email by POST'ing a message to the API:

def send_text_message():
  # Sending a simple text-only message using Mailgun HTTP API.
  # Notice the 'servername' parameter - it is your virtual mailserver
  # provided by Mailgun. You can get as many as you want.
  MailgunMessage.send_txt(
    sender     = "me@myhost.com",
    recipients = "you@myhost.com, him@myhost.com",
    subject    = "Hello!",
    text       = "Hi!\nI am sending you a text message using Mailgun",
    servername = "my-mailserver.com")

Good old SMTP is also supported, so your email server can be configured to relay mail via Mailgun.

Receiving email

Mailgun uses the same "routes" notion employed by major MVC frameworks like Ruby on Rails or Django: you define a set of routes that look at incoming email addresses, apply pattern-matching and POST matched messages to your controllers via HTTP.

All messages are guaranteed to be in UTF-8 format (regardless of the original encoding) making it simple to programmatically digest the contents of the email. Multipart emails are split into text and HTML. Attachments are POST'd to the specified URL as files. Here is a code sample showing how to handle an incoming message:

# POST http://host.com/upload
def upload(request):
     if request.method == 'POST':
         sender    = request.POST.get('sender')
         recipient = request.POST.get('recipient')
         subject   = request.POST.get('subject', '')

         body_html  = request.POST.get('body-html', '')
         body_plain = request.POST.get('body-plain', '')

         for key in request.FILES:
             file = request.FILES[key]
             # do_something_cool_with(file)

     # Returned text is ignored but HTTP status code matters:
     # Mailgun wants to see 200, otherwise it will make another attempt
     return HttpResponse('OK')

Using routes

Mailgun routes allow you to define where Mailgun should send incoming messages. A route is a pair consisting of a pattern and a destination. The recipient of each incoming message is matched against pattern in your routes and, if there is a match, Mailgun forwards the message to the destination of that route. Routes can be created, updated, and deleted via the API or the control panel. Here is a code sample showing how to create a route via the API:

Mailgun.init("api-key-secret")
route = Route.make_new( pattern = 'me@myhost.com',
                        destination = 'http://myhost/accept_mail' )
route.upsert()

Email Deliverability

Your email reputation is incredibly important. Without a good email reputation, your email will be marked as spam by ISP's. Mailgun insures that the messages you send will make it to their intended destination. We leverage the following tools to ensure that your messages will not be dropped or sent to spam by ISPs and major email providers:

Automatic SPF for all outbound email from our servers
Automatic DKIM and DomainKeys signing of outbound mail
SenderID support
Bounce detection and proper handling: you will not be penalized by repeated attempts to deliver to non-existing mailboxes
ISP sending rates: we keep the ISP's happy by monitoring the frequency of emails and complying with ISP rate limits

Mailgun also "warms up" server IPs before giving them to you and monitors the various black listing services and should one of your IP's end up blacklisted, we'll quickly take the steps required to restore the IP to clean status.

Flexibility

We have built Mailgun for fellow programmers. It is flexible, programmable and configurable. The use cases are only limited by your creativity. Nothing stops you from giving every web page or every object in your application its own email address, so you can build features that take advantage of email as an important user interface. Our mail queues are so fast and efficient that some of our customers are using Mailgun as a generic software-to-software cross-firewall message broker. After all SMTP is just a protocol and both sender and recipient mailbox owners can be machines. If you are using Mailgun in an interesting way, drop us a line. Perhaps we could add a feature that makes your app even more powerful.

Want to learn more?

The best way to learn more about Mailgun is to try it out. Sign up to get your own virtual email server. You'll be sending and receiving messages programmatically in just a few minutes.

Contents