DEV Community

Cover image for I Built an Email API — Here's What I Learned About DKIM, SPF, and DMARC
Johan S
Johan S

Posted on • Originally published at sendpigeon.dev

I Built an Email API — Here's What I Learned About DKIM, SPF, and DMARC

#emailauthentication #awsses #buildinginpubilc

When I started building SendPigeon, I assumed email would be the easy part.

SMTP has been around forever, AWS SES is reliable, and sending an email looks like a solved problem. I expected the hard parts to be scaling, APIs, and dashboards.

Instead, almost all of the real complexity showed up in one place: email authentication.

Modern email delivery isn't really about SMTP anymore. It's about DNS, cryptographic signatures, and trust policies enforced by inbox providers. If any of that is wrong, emails don't just land in spam — they often disappear entirely.

This is a technical deep dive into what I learned building an email API on top of AWS SES, specifically around SPF, DKIM, and DMARC.

Email is a trust system

SMTP was designed in a much friendlier era of the internet. There was no built-in authentication, which made spoofing trivial.

To compensate, the ecosystem evolved three layers of defense:

  • SPF answers: Is this server allowed to send email for this domain?
  • DKIM answers: Was this message altered in transit?
  • DMARC answers: What should receivers do if something fails?

Today, inbox providers like Gmail and Outlook expect all three to be present and correctly aligned.

SPF: declaring who can send

SPF (Sender Policy Framework) is a DNS record that specifies which servers are allowed to send email for a domain.

A minimal SES SPF record looks like this:

v=spf1 include:amazonses.com -all
Enter fullscreen mode Exit fullscreen mode

This tells receiving servers:

  • Email is valid if it comes from AWS SES
  • Everything else should fail

What I learned quickly is that SPF is fragile.

Some of the issues I ran into:

  • There's a hard limit of 10 DNS lookups
  • Users often combine multiple providers (SES, Google, marketing tools)
  • Soft fail (~all) vs hard fail (-all) decisions matter more than people think

More importantly, SPF checks the envelope sender, not the visible From: header. When you're sending email on behalf of customers, this distinction becomes critical.

And SPF alone is not enough — inbox providers increasingly treat SPF-only email as suspicious.

DKIM: proving message integrity

DKIM signs outgoing emails with a private key. The recipient retrieves the public key from DNS and verifies the signature.

AWS SES handles DKIM signing well, but understanding what it protects — and what it doesn't — is important.

DKIM signs:

  • Selected headers (From, Subject, Date, To)
  • The message body
  • The overall structure of the email

If any signed part changes in transit, the signature fails.

Some subtleties that matter in practice:

  • Alignment matters. DKIM can pass and still hurt deliverability if it doesn't align with the From: domain.
  • Multiple DKIM signatures can coexist, but if the wrong one is checked or one fails, it can cause confusion.
  • Key rotation is a security best practice — not proven to affect deliverability, but worth doing.

One of the more surprising things I saw was DKIM passing while deliverability still suffered — the culprit was always alignment.

DMARC: the glue everyone ignores

DMARC ties SPF and DKIM together and tells inbox providers what to do when authentication fails.

A basic DMARC record might look like this:

v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com
Enter fullscreen mode Exit fullscreen mode

This puts a domain into monitoring mode.

What DMARC taught me:

  • Aggregate reports are incredibly valuable. They show who is sending email for your domain, including sources you didn't know about.
  • p=none isn't enough long-term. Domains that never enforce policy tend to earn less trust.
  • Subdomain policy matters, especially if you send from subdomains like mail. or notifications..

The typical progression:

Policy Effect When to use
p=none Monitor only Start here
p=quarantine Failures go to spam After 2-4 weeks
p=reject Failures blocked entirely When confident

DMARC is where email authentication stops being theoretical and becomes operational.

Where AWS SES fits in

AWS SES gives you solid primitives:

  • High-quality sending infrastructure
  • Automatic DKIM signing
  • Bounce and complaint events

What SES doesn't give you is an opinionated model.

It won't:

  • Enforce alignment
  • Validate user DNS configuration
  • Prevent misconfiguration
  • Surface silent failures

When building SendPigeon, most of the work wasn't "sending email" — it was building guardrails around SES so that mistakes were visible instead of invisible.

Deliverability is a product feature

The biggest lesson I learned is that email authentication isn't just infrastructure — it's UX.

If users misconfigure SPF or DKIM and emails quietly fail, that's not an ops issue. That's a product failure.

Good email systems:

  • Make misconfiguration hard
  • Make failures obvious
  • Default to secure, aligned setups

Things I wish I knew before using SES

If you're building on SES yourself:

  • Enforce DKIM alignment early
  • Generate DMARC records by default
  • Store and analyze DMARC reports
  • Validate SPF lookup counts
  • Assume users will misconfigure DNS

Because they will.

Closing thoughts

Building SendPigeon forced me to understand email at a much deeper level than I expected.

Email delivery isn't about sending messages — it's about earning trust, one DNS record at a time.

If you get SPF, DKIM, and DMARC right, email becomes boring.

And boring email is the best kind of email.

Learn more

Top comments (0)