Use Mailgun with Moodle for Outbound Email

Notes

• Through this document we will use lms.example.com as a test case, however any username or credentials shown will have been modified to be intentionally invalid for obvious reasons.

• Mailgun is no longer free. Consider using something like Mailjet.

Pre-flight check.

We use a new mailgun account for each environment. Create a new account based on the current project and make sure to save and forward the credentials to the responsible engineer. Best to use a custom email address for future transfer possibilities, e.g. admin@lms.example.com.

Verify you have the right credentials, and that you are able to login to the following services:

• Mailgun account.

• Moodle site administration.

• Domain DNS settings, these might live inside the Domain Registrar’s administration panel, or they might reside in an external service (Cloudflare, for example).

Specifically, it is common for services like Mailgun and DNS settings to be protected by 2 Factor Authentication. If that is the case, you will need to coordinate with your lead engineer to find a change window with the client so they are able to forward the second factor tokens to you.

• If you use GMail and have enabled login codes through an app or SMS, this is a good example of working 2-Factor Authentication.

It goes without saying that disabling 2-Factor Authentication is something we must not do once we are logged in. If necessary, multiple additional change windows can be requested.

Mailgun

What is Mailgun

Mailgun is an online service that provides a set of APIs for sending, receiving, tracking and storing email. It can be used through an HTTP REST API, or as a traditional SMTP server.

Mailgun handles all the complex email stuff: the software services themselves, and all the email dark arts that surround them (SpamHaus, shared IPs, IP reputation, warming up IPs, the software side of DKIM and friends). We can stick to the explicit action we want to perform: sending emails, and let Mailgun worry about the rest.

We are going to use Mailgun in SMTP mode, and we will add their SMTP server to Moodle so transactional emails are sent this way.

Create an account for Mailgun

• Go to https://signup.mailgun.com/new/signup and create an account. Use your own email address and for “company” a combination of Solin with the company name of your customer.

• You also have to provide credit card details otherwise you can only send emails to 5 authorized recipients only. In case the account details are shared with the customer, make sure that you do not share credit card details from your colleagues!

• Save the login details of this account in your password wallet and send it to the responsible engineer as well.

Adding the domain to Mailgun

• After logging into the account, enter the “Domains” section (navigation pane Sending>Domains) and click on “Add New Domain”.

• At the “Add your domain” page fill out the following details and click on Add Domain:

  • Domain name: Always use a subdomain to prevent any problems with the root domain. Use in this case mg.examplemail.com

  • US/EU: Select the location of the sending server: For all companies residing in countries except from US, select EU. For the United States, select US.

  • Create DKIM Authority: leave this checked and select the longest DKIM key that is possible.

Domain or subdomain? What is the difference?

Explained in simple terms, these domains are going to develop a reputation over time depending on the rate of email delivery and the amount of times our users click on “Mark as Spam”.

Using the root domain is possible when it doesn’t have any MX records yet. However, to prevent any problems, we will always use a subdomain when we implement Mailgun.

A longer, more detailed read on this topic is available on Mailgun’s documentation.

Now that we have added the domain, we need to prove our ownership of it to Mailgun.

Proving to Mailgun that we own the domain.

Mailgun allows us to send email from any address and domain, as long as we can verify them. To do so, we will add specific TXT records through the DNS server of the domain. These records are generated and shown as soon as you click on the “Add Domain” button. You can also find these records by navigating to Sending>Domain Settings and tab DNS records. Make sure you select the correct domain on top of the page.

The DNS settings might live inside the domain registrar’s interface, or they might reside in an external service if we are using other services to manage the DNS (Cloudflare, for example).

Finding out who manages the DNS servers for the domain

Linux: Use the dig command.

$ dig +short NS lms.example.com

clint.ns.cloudflare.com.

dorthy.ns.cloudflare.com.

Windows: Use nslookup

nslookup -type=ns lms.example.com
Server: 198.51.100.10
Address: 198.51.100.10#53
Non-authoritative answer:
lms.example.com nameserver = clint.ns.cloudflare.com.
lms.example.com nameserver = dorthy.ns.cloudflare.com.

You can also use an online tool to find the hosting details: lms.example.com/

The DNS server for lms.example.com is managed by Cloudflare, which means we will need credentials to access the customer’s Cloudflare account.

Adding TXT records to the domain’s DNS settings

In this particular case, we are going to modify Cloudflare’s DNS settings. The process will be similar with other providers, and Mailgun offers helpful manuals for GoDaddy, NameCheap, Network Solutions, Rackspace Email & Apps, Rackspace Cloud DNS, Amazon Route 53 and Digital Ocean. Consult each provider’s help section if you have doubts about this.

For more general instructions, go to https://help.mailgun.com/hc/en-us/articles/360026833053-Domain-Verification-Walkthrough

• Login to your hosting provider. This account might be applicable for several domains.

• Select the domain of the Moodle website.

• Navigate to the DNS section. Look for a section called Advanced domain settings or Manage DNS.

• Add all records with the type, hostname and value that Mailgun has provided:

  • Add two separate sending TXT records, one for SPF and one for DKIM. These are required to send and receive email with Mailgun.

  • Add two separate receiving MX records. Use for priority 10.

  • Add a tracking CNAME record. The CNAME record is what enables Open and Click tracking. This is highly recommended to reap the full benefit of Mailgun and gain insights into your email performance.

• Once you have added all records, you can click in Mailgun at the DNS records page on the button “Check DNS Records Now” to verify the records. If they have been verified, you see a green check sign in front of the record.

• You will also receive an email from Mailgun once the DNS records have been verified.

If you are not familiar with DNS’ innerworkings, it might surprise you to read that this change might take up to 48 hours to propagate. Basically, TTL is the amount of time that records will be kept in cache throughout the whole DNS hierarchy; from the root servers to the servers that you use as DNS servers (such as 198.51.100.11).

GoDaddy “Helps” by Adding Your Full Domain in Name Part

Please note that GoDaddy doesn’t clearly tell you that it automatically appends the domain name to the “Name” field — which leads to lots of confusion, especially when you’re used to entering full FQDNs (Fully Qualified Domain Names) elsewhere.

In short, when using GoDaddy’s interface, do not enter the full domain name, just the subdomain you’re editing.

For example, if you have this DNS record:

• then you should enter this as “mail”.

Integrating Mailgun with Moodle.

Now that we can send emails as admin@lms.example.com, it’s time to configure Moodle to send email through Mailgun.

Obtaining the credentials from Mailgun

• Go to Sending>Domain settings and click on the SMTP credentials tab.

• Here you cannot see directly the password, but you can reset the password to be able to copy it to your password wallet and use it in Moodle.

• Follow the instructions on https://help.mailgun.com/hc/en-us/articles/203380100-Where-Can-I-Find-My-API-Key-and-SMTP-Credentials-

Beware: Anyone with the password and SMTP login will be able to send email as <anyone>@lms.example.com. Treat these credentials with utmost care.

Configuring Moodle

• Go to the Moodle website and log in as an Administrator.

• Click on Site Administration> Server> Outgoing mail configuration

• Fill in the fields with the information obtained in the previous step, and click save.

If you want to have SMTP security enabled, please select the appropriate security mode.

For secure connections, port 465 is usually used with SSL, port 587 is usually used with TLS.

Done! Moodle is now configured to send email through Mailgun. Let’s test this setup, to confirm everything is working.

Send a test email.

From the shell.

Using swaks (available in the Debian/Ubuntu repositories) we are going to send a test email that will come from admin@lms.example.com.

$ swaks -auth -server lms.example.com -au
admin@lms.example.com -ap <smtp password> -from
admin@lms.example.com -to email@lms.example.com -h-Subject: "Hello"
Test
=== Trying lms.example.com:25...
=== Connected to lms.example.com.
<- 220 ak47 ESMTP ready
-> EHLO example-client
<- 250-ak47
<- 250-AUTH PLAIN LOGIN
<- 250-SIZE 52428800
<- 250-8BITMIME
<- 250-ENHANCEDSTATUSCODES
<- 250-SMTPUTF8
<- 250 STARTTLS
-> AUTH LOGIN
[..]
<- 235 2.0.0 OK
-> MAIL FROM:<admin@lms.example.com>
<- 250 Sender address accepted
-> RCPT TO:<email@lms.example.com>
<- 250 Recipient address accepted
-> DATA
<- 354 Continue
-> Date: Sun, 04 Feb 2018 20:53:12 +0100
-> To: email@lms.example.com
-> From: admin@lms.example.com
-> Subject: Hello
-> X-Mailer: swaks v20130209.0 lms.example.com/john/code/swaks/

->

-> This is a test mailing

->

-> .
<- 250 Great success
-> QUIT
<- 221 See you later. Yours truly, Mailgun
=== Connection closed with remote host.

From Moodle.

(Note: if the plugin is not installed, you can install it from https://moodle.org/plugins/local_mailtest. However, be mindful of the customer’s environment! If you have any doubts about this step, please check with your lead engineer before proceeding.)

Go to Server/eMail Test and fill in the fields.

Moodle will show you exactly what happened, and if the email was sent successfully or not. Debug mode settings do not affect the rest of the website, and detailed output is always shown on error regardless of the debug settings specified in Moodle’s config.php.

Troubleshooting

SMTP ERROR: Failed to connect to server.

Either:

• You have selected SSL in the SMTP settings, and it should be disabled since we are using plaintext auth.

• The service provider is blocking port 25, 465 or 487.

If it’s due to port blocking, Mailgun has an extensive article on this issue and how to work around it.

• TL;DR: Use port 2525 instead.

To Do: Add Section on DMARC

• User lms.example.com/dmarc-record-wizard/ to create a dmarc record

  • Use admin@lms.example.com as the recipient

• To do: add DNS record to solve this: “solin.co is missing the required DNS TXT record to authorize the receipt of aggregate reports from lms.example.com. This is a requirement of the DMARC specification and you may be missing data as a result.”

  • Use lms.example.com/dmarc-inspector/ to see if the DMARC record was successfully added.

• See also https://www.mailgun.com/blog/deliverability/implement-dmarc/#:~:text=Domain%2Dbased%20Message%20Authentication%2C%20Reporting,emails%20on%20your%20sender%20program.