TLS Connection Control

Mailgun Team

• 5 min read

This blog post was originally published in 2015. Over a year ago Mailgun flipped on opportunistic TLS. This means whenever we connect to an MX server, we first try and upgrade the connection to a TLS connection to deliver your messages. However, if it’s not offered or some kind of error occurs (like an invalid certificate) while establishing the connection, we still deliver the message, but over a plaintext SMTP connection.

Since then we’ve had customers request we expose more functionality and information for message delivery. That’s why we are releasing a few delivery related features today:

Force message delivery to only occur over a TLS connection.
Enable or disable certificate verification.
Expose the MX server we delivered the message to in our Logs.
Expose the TLS state of the connection in our Logs.

Overview

For message delivery, we will expose two new flags that will work at the domain level or message level (message level will override domain level) that allow you to control how messages are delivered:

require tls: If set to True this requires the message only be sent over a TLS connection. If a TLS connection can not be established, Mailgun will not deliver the message. If set to False, we will still try and upgrade the connection, but if we can not, we will downgrade and deliver over a plaintext SMTP connection. The default is False.
skip verification: If set to True, the certificate and hostname will not be verified when trying to establish a TLS connection and Mailgun will accept any certificate during delivery. If set to False, Mailgun will verify the certificate and if it can not, a TLS connection will not be established. The default is False.

Details on how the message was delivered will be exposed in our Logs, look for a few additional flags under the delivery-status document:

tls: This indicates if a TLS connection was used or not when delivering the message.
certificate-verified: This indicates if we verified the certificate or not when delivering the message.
mx-host: This will tell you the MX server we connected to to deliver the message.

Examples

If you have a single message you would like to deliver with custom connection settings, you can send it like so:


1curl -sk --user 'api:API_KEY'   
2    https://api.mailgun.net/v3/DOMAIN_NAME/messages 
3    -F from='foo@example.com' 
4    -F to='bar@example.com' 
5    -F subject='Hello' 
6    -F text='Testing some Mailgun awesomness!' 
7    -F o:require-tls='false' 
8    -F o:skip-verification='true'

If you would like to configure an entire sending domain to deliver messages in a particular manner:


1curl -sk --user 'api:API_KEY'   
2    -X PUT https://api.mailgun.net/v3/domains/DOMAIN_NAME/connection 
3    -F require_tls='false' 
4    -F skip_verification='true'

Check that your configuration was correct:


1curl -sk --user 'api:API_KEY'   
2    -X GET https://api.mailgun.net/v3/domains/DOMAIN_NAME/connection

Lastly, if you take a look at your Mailgun Logs, you should see the delivery-status document has the new fields mentioned above.


1"delivery-status": {
2  "tls": true,
3  "certificate-verified": true,
4  "mx-host": "aspmx.l.google.com",
5  "code": 0,
6  "description": null,
7  "session-seconds": 0.6860120296478271,
8  "message": ""
9}