Email Tools in an API World Laptop w Gears

Modern Email Tools Available To You

Email has a long heritage of standards and specifications, many of them are truly great and some are even followed. Implementing these standards requires considerable knowledge. Tools ease our work by encompassing that knowledge, packaging it up and making it available to all. One strong measure of a tool’s worth is its effectiveness at embodying knowledge and reducing cognitive load on the wielder.

The world of email tools is almost as rich as its body of standards. We have myriad services, applications, libraries and commands for configuring, testing, orchestrating and tracking our various messaging activities. The email industry is hugely advanced in the orchestration, delivery and tracking spaces, since those are where the broadest commercial interest lies. Unfortunately, tooling for email service configuration and testing is less advanced, possibly since those tools would merely improve engineers’ lives.

Suffice to say, there is still considerable knowledge required to configure, verify and troubleshoot one’s email estate.

Let’s look at a typical setup task that most email senders have grappled with: configuring DKIM signing for an email sending domain. DKIM allows you to take responsibility for the messages you send by associating your sending domain with your mail. Don’t worry too much if you don’t 100% follow all these steps. The intent is to show level of effort.

DKIM Setup: The Old School Way

Here are some outline steps we might follow to start signing our email.

  1. Generate an RSA key pair:
openssl genrsa <KEY_LENGTH> -outform PEM -out dkim-key-pair.pem

-----BEGIN RSA PRIVATE KEY-----
MIICXAIBAAKBgQC31jzPQs2ZmjEz+yrL/9VHYJ6*YOroHIOdDLwjyypDwhjozuAu
ZFWcecZRY+6MxU17MpSWRv27rlUolOMxv6D/lJoaw3vdy0uuuGiWUD7lj5VtPok8
4V9VeymkAxVPZHn8y1w9P9WNHlBrillsx+NMDiMZijUYpTa6zKbkxRhhBQIDAQAB
AoGADjAorU5Yk9xEo+Bkoy3xhfq9BbBxMMzSk5JiCtkpP+WBCqa8wpfXy6XSWoG9
7XtkyXdT5G1CM/P2epVTG4nQoQdbVIJ8aov6Ra9wbza5ViS8iTfqlk4DRv2NOLRM
KFs/9r4ST+KobLrSf4MCjkxMIZdPSwZU4vO9MaSmLf92XxkCQQD0du7dkFR0Dp0L
pX9SrUfB612cR2aMVp57ira4MC8vZYLeALYDYuqkTL61/mnLGdez2OXI3mM55q52
6b0i4KG/AkEAwILwFT8yq+xO1G+/eQlSlsP6JqubY23jzLGKHZp9Q4n/8sU1zS9Z
u7+8V4prnJnIZfy/XVUGKmtpENAnC19mOwJAcAoiJ4GCcz5PU4sh825fOMz6Nimz
IhaAw/YrD/dlaL+JXt3MjXjEOVDDBv321pKdfVum1Iy3xU2oH++4M0foWQJALBvU
NooMaifyx+nyzSC9s52jq0iWiemb0EK9iprjKJ5t7ooREbpPrRz5YnVswqzZpcSL
dC8PApkpsZh/2bM6EQJBAKzm150hcGSCHEDZ4Q+1PPK/uUTC7jQVsj4uvEJh22SG
qq8ZXn4CjNgf1jcID+q2Bp3EYsBYYU3auJbeG8o8oDo=
-----END RSA PRIVATE KEY-----

2. Extract just the public key:

openssl rsa -in dkim-key-pair.pem -out dkim-public-key.pem -pubout -outform PEM

-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCpK4SsMTE9mefdRciuvOfQaqR8
URPv+hy9x0VloOpu9FYirWeo0+l5VGRt7LgHGscMB5yR8RoFDxXRQYe8x7QXuRnq
oFcegwzFCUovEutbfIA7sxL6r/tYzIuakjEb7uC3fehjQTJgmHeZ8Xm4jjhl+8Ng
W2mHMllmc7K9tqzqqQIDAQAB
-----END PUBLIC KEY-----

3. Form our DKIM DNS record from public key:

v=DKIM1\; k=rsa\; h=sha256\; 
p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCpK4SsMTE9mefdRciuvOfQaqR8URPv+h
y9x0VloOpu9FYirWeo0+l5VGRt7LgHGscMB5yR8RoFDxXRQYe8x7QXuRnqoFcegwzFCUovEu
tbfIA7sxL6r/tYzIuakjEb7uC3fehjQTJgmHeZ8Xm4jjhl+8NgW2mHMllmc7K9tqzqqQIDAQ
AB

4. Have our DNS provider publish the DKIM record under

selector._domainkey.yourdomain.com

5. Configure our email service to sign using your private key.

With that done, these ancillary points are left as an exercise for the reader:

DKIM Setup: The SparkPost Way

Ok, let’s try that again, this time using the SparkPost API.

  1. Ask SparkPost to create our sending domain and a matching DKIM key pair
    (we can also do this in the app):
curl -XPOST https://api.sparkpost.com/api/v1/sending-domains -H 
“Authorization: YOUR_API_KEY” -d ‘{“domain”=”example1.com”, 
“generate_dkim”: true}’

{
 "results": {
 "message": "Successfully Created domain.",
 "domain": "example1.com",
 "dkim": {
 "public": 
"MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC+W6scd3XWwvC/hPRksfDYFi3ztgyS9OS
qnnjtNQeDdTSD1DRx/xFar2wjmzxp2+SnJ5pspaF77VZveN3P/HVmXZVghr3asoV9WBx/uW1
nDIUxU35L4juXiTwsMAbgMyh3NqIKTNKyMDy4P8vpEhtH1iv/BrwMdBjHDVCycB8WnwIDAQA
B",
 "selector": "scph0316",
 "signing_domain": "example1.com",
 "headers": "from:to:subject:date"
 }
 }
}

2. Form our DKIM DNS record using API result
(Hint: SparkPost will show us the fully-formed record here):

v=DKIM1\; k=rsa\; h=sha256\; 
p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC+W6scd3XWwvC/hPRksfDYFi3ztgyS9O
SqnnjtNQeDdTSD1DRx/xFar2wjmzxp2+SnJ5pspaF77VZveN3P/HVmXZVghr3asoV9WBx/uW
1nDIUxU35L4juXiTwsMAbgMyh3NqIKTNKyMDy4P8vpEhtH1iv/BrwMdBjHDVCycB8WnwIDAQ
AB

3. Have our DNS provider publish the DKIM record

4. Verify our setup by clicking the DKIM record test button for your sending domain in SparkPost

Side note: Here are all the tasty the details on using SparkPost to manage and verify sending domains and also using the SparkPost API sending domains endpoint itself.

Much Better…

Now we’re a tiny bit biased but we do love our email API and it certainly reduces the user’s cognitive load here. Questions we no longer need to worry about:

  • What size should the RSA key be?
  • What even is an RSA key pair?
  • How do we invoke the openSSL toolkit correctly?
  • How do we handle our private key material safely?
  • How do we format our DKIM DNS record?

That single API call executes sending domain configuration, creates our DKIM keys and formats our DNS record all at once. There’s less to do, less to understand and fewer places to stub our toes along the way.

…But Not Perfect (Yet)

…and yet there are further submerged rocks to run aground on here. The DNS record could be fat fingered during publication, the DNS provider may truncate the record and what do you do if there’s an existing DKIM DNS record for your domain? How do we diagnose each of these and how do we verify the end-to-end DKIM signing and verification process?

These are all issues and questions we’ve seen in production use. Clearly, there’s more we could do, as a tool-loving developer community, to help each other be more reliably successful, faster and just plain happier in our work. Just as SparkPost has an email API, DNS services have record management APIs. Combine these with the modern web and we could build far better experiences for each other. For starters, how about:

  • A DKIM verification tool explicitly designed for diagnostic and remedial use (stay tuned for next week’s post!)
  • A modern validating SPF record editor
  • Open DMARC as a service

Against a background of modern API-driven workflows, email tooling looks a generation or so out of date. In the SaaS email infrastructure community, we can do better. Isn’t it about time for a new generation of messaging tools?

If you liked, hated, agreed, disagreed or just want to chat about email infrastructure, tooling, APIs or anything else, come join our burgeoning Slack Community. We’d love to hear from you.

—Ewan