The Problem

Email is easy but using email effectively is hard. It's easy for an OpenInsight developer to use the rti_cdomail function to send an email message without concern for what happens to the message after the function returns. The process becomes a lot more difficult when the developer must deal with:

• Un-subscription link tracking and response

• Verifying message delivery from within code

• Handling bounced messages

• Each client site having a different mail server configuration

• Bad email reputation delyaing message delivery

With enough time and resources each of these challenges can be addressed by the developer and staff resources but the goal of this article is to leverage existing email services for use in OpenInsight to address these problems and reduce the use of staff resources to manage email.

If you haven't already e-mail enabled your OpenInsight application or O4W site (or are looking to increase e-mail usage) this Coding Horror blog post should enlighten on you about the difficulting of sending email from code and doing it right. Unlike the Coding Horror blog post we'll be looking at Mailgun.

Introducing Mailgun

Mailgun is a managed email service provided by RackSpace. Unlike a traditional email account for sending and receiving messages Mailgun is focused on making the email server accessible to developers.

The service has a very generous free account account (10,000 messages per month as of this post) and easy setup for use with OpenInsight. The service offers outbound SMTP servers for use with RTI_CDOMail for use within OpenInsight and a flexible API for advanced email interactions. I'm not affiliated with Mailgun and encourage you to checkout the site if you want more information. Since I'm not writing a sales pitch we'll get on with the technical goodness.

Creating a Mailgun Account for Testing

In just a few steps you can signup and test mailgun for yourself.

1. Go to https://mailgun.com/signup and signup for an account. It’s easy, really! After signing you'll have a sandbox domain and login information to test mailgun but we'll skip this and add our own domain.

2. Add a domain to your mailgun account. This is the domain that will appear as the sender of your email. In this example my domain will be openinsight.mailgun.com

3. In the next step you’ll be prompted to add DNS records to your domain. Skip this step and continue to the next screen. This step is optional unless you intend to have mailgun receive messages. Adding DNS records will also help reduce the changes that email sent from mailgun is marked as spam. Should you decide to add the DNS records all of the information is provided. Below is an example of the Amazon Route53 DNS records for openinsight.congruityservice.com:
   

4. The domain information page will display, note the following information from your domain information page:

   SMTP Hostname
   Default SMTP Login
   Default Password
   
   The image below shows the example openinsight.congruityservice.com domain information with the important parts highlighted. The SMTP port we’ll be using is standard 587.
   
   

Using the settings from the domain information page we can now send mail from OpenInsight. The following is a sample BASIC+ routine TEST_MAILGUN taken from the RTI_CDOMail help file page. Use this routine by copying it into OpenInsight, replacing the appropriate variables with the settings from your mailgun account, and execute it.

Subroutine TEST_MAILGUN(params)
Declare Function rti_cdomail

*Email address the message will appear to be sent from
*Replace with your domain, the email address need not exist for testing.
sendername      = 'oitest@openinsight.congruityservice.com'

*Where the email will be sent, i.e. your address.
recipient       = '--redacted--@example.com'

*Mailgun login information from domain information page.
*Replace with your mailgun domain information settings
mailservername  = 'smtp.mailgun.org'
username        = 'postmaster@openinsight.congruityservice.com'
password        = '--redacted--'

mailserverPort  = '587'; *Use port 587 and SSL
useSSl          = 1
mailServer      = mailServerName:':':mailserverPort

subject         = 'Sent through Mailgun'
body            = 'This is a test of CDO Mail using Mailgun'

retval = rti_cdoMail( mailserver, sendername, recipient, subject, body, cc, bcc, replyto, content, attachmentfilelist, username, password, useSSl )
Return

Why Mailgun?

Google, your ISP, or hosting provider can all provide you with SMTP access for sending messages but that is it. Apart from all the API features we've yet to cover an incredibly useful reason to be familiar with Mailgun is you can immediately see the server logs to check the status of your messages right from the mailgun account page. By clicking Log at the top of the mailgun menubar you'll be able to see the activity of the SMTP server in an easy to use format. The image below is the result of sending messages through the example account.

Notice the log indicates each message was Accepted and Delivered. Accepted means the OpenInsight BASIC+ routine successfully transmitted the message to mailgun using SMTP. Without this information it will be difficult to determine if the message failed to send because of an error in your program or a problem with the email address. The Delivered log message indicates that the message was transferred from the Mailgun server to the recipients email server. Delivered messages should be in the recipients mailbox.

With other email services this information is usually only available by checking with the SMTP server administrator which can be tedious to do when you're trying to debug code.

What's next?

This was only an introduction to using Mailgun and OpenInsight. The next several blog posts in the series will focus on using JSON to interact with the Mailgun API for more advanced features such as sending messages through the API and processing message responses. If nothing else I hope you are able to utilize mailgun to ease the headache of sending email and debugging code.

Disclaimer: I am not affiliated with Mailgun