All posts Engineering

The journey of an email: from API call to inbox

A step-by-step walkthrough of what happens to an email between your API call and the recipient's inbox: validation, message assembly, DKIM signing, DNS routing, the SMTP handshake, authentication, content filtering, and placement.

Erik Vlčák

Customer Success Engineer

February 18, 2026 11 min read

Sending an email looks like one line of code: a POST /emails request, then a 200 OK a few milliseconds later. It looks instant and simple, but behind that single call the message is validated, assembled into a standard format, cryptographically signed, routed through DNS, and checked for reputation and spam before a mail server decides where it lands. A lot has to happen before that message reaches a real inbox, and each stage hides a failure that can drop or misroute it.

Step 1: Submission and validation

The email starts as structured data: a from address, a to address, a subject line, an HTML body, and maybe attachments. Before accepting any of it, the service checks that the from address belongs to a verified domain, that attachments are within size limits and use allowed file types, and that any template resolves and merges its data cleanly.

The most important check happens against the suppression list. Addresses that previously hard-bounced or filed spam complaints are blocked outright, because resending to them would damage the sender's reputation. Only once everything passes does the API return success and queue the message for assembly.

Step 2: Message assembly

The raw API data is now formatted into a standard email message: a set of headers (From, To, Subject, Date, Message-ID, and others) followed by the body. The structure is defined by RFC 5322 and has barely changed since the early 1980s.

The body is usually wrapped in a MIME multipart structure carrying both an HTML and a plaintext version, separated by a boundary string, so each receiving client can render whichever it supports. Attachments ride along as Base64-encoded parts. Once assembled, it all becomes a single plain-text document like this:

From: notifications@yourapp.com
To: user@gmail.com
Subject: Verify your email address
Date: Tue, 04 Mar 2026 10:30:00 -0500
Message-ID: <abc123@yourapp.com>
MIME-Version: 1.0
Content-Type: multipart/alternative; boundary="boundary123"

--boundary123
Content-Type: text/plain; charset=UTF-8

Click here to verify: https://yourapp.com/verify?token=xyz

--boundary123
Content-Type: text/html; charset=UTF-8

<html><body><a href="https://yourapp.com/verify?token=xyz">Verify</a></body></html>
--boundary123--

Step 3: DKIM signing

Before the message leaves, it gets a cryptographic signature called DKIM (DomainKeys Identified Mail). The sending server hashes key headers and the body, signs that hash with a private key, and adds it as a DKIM-Signature header. The matching public key lives in a DNS record on the sender's domain, so any receiver can fetch it and check the signature. If anything in the message changed along the way, the check fails.

Providers usually handle key generation and signing for you. Lettr generates the DNS records and verifies them during domain setup.

Step 4: DNS lookups and routing

With the message assembled and signed, the sending server needs to find where it goes. It looks up the recipient domain's MX (Mail Exchange) records, which name the hosts that accept mail for that domain. When several exist, the server tries the lowest-numbered one first (lower means higher priority) and falls back to the rest. If the lookup turns up nothing, the message bounces immediately as unroutable.

Step 5: The SMTP handshake

The sending server opens a TCP connection to the recipient's mail server and talks SMTP (Simple Mail Transfer Protocol). Despite the name, the conversation is structured:

Sending server: EHLO mail.yourprovider.com
Receiving server: 250-smtp.gmail.com at your service
Sending server: MAIL FROM:<notifications@yourapp.com>
Receiving server: 250 OK
Sending server: RCPT TO:<user@gmail.com>
Receiving server: 250 OK
Sending server: DATA
Receiving server: 354 Start mail input
Sending server: [the full RFC 5322 message from step 2]
Sending server: .
Receiving server: 250 2.0.0 OK

That final 250 is what "delivered" means in email: the receiving server has accepted the message and taken responsibility for it. What it does not mean is that the message reached the inbox. Everything after the handoff happens on the receiver's side, where the sender has no visibility.

Step 6: Authentication checks

Once the receiver accepts the message, it verifies the sender's identity using three checks that work together:

SPF (Sender Policy Framework) checks whether the sending server's IP is on the list of addresses the domain authorizes to send for it, published as a DNS record.
DKIM verifies the signature from Step 3: the receiver fetches the public key from DNS and confirms the message was not altered in transit.
DMARC is the policy layer. It tells receivers what to do when SPF or DKIM fail (none, quarantine, or reject) and requires that the From domain match the one that passed SPF or DKIM.

Lettr verifies SPF, DKIM, and DMARC alignment during domain setup, so misconfigurations surface before the first send rather than as mysterious placement failures weeks later.

Step 7: Content filtering

Authentication tells the receiver who sent the message; content filtering decides whether it is wanted. The exact rules are proprietary, but the priority order is well understood, with reputation at the top. The sending domain carries a score based on how recipients treat its mail: opens, replies, and moves out of spam boost it, while complaints and invalid addresses drag it down.

Content analysis is only a tiebreaker. The filter scans for spam patterns (excessive capitalization, deceptive links, known phishing phrases, suspicious image-to-text ratios), but a legitimate receipt and a phishing email can look nearly identical, which is why reputation carries the weight when the content is ambiguous. Reputation is not even uniform across recipients: if one user never opens a sender's mail, Gmail may route it to spam for that user alone, while everyone else sees it in their inbox.

Step 8: Placement

After authentication and content filtering, the receiver makes the final call, and the message lands in one of three places:

Inbox is the goal, though in Gmail it may sit in Promotions or Updates with much less visibility.
Spam/Junk means the message was accepted but hidden where almost no one looks.
Out-of-band rejection is the trickiest: the server returned a 250 during the handshake, then decided not to deliver and sent a bounce minutes or hours later, after delivery already looked successful.

Spam placement is the dangerous one because it is completely silent. There is no error code and no webhook when a message is filtered; the delivery rate stays high while the open rate quietly collapses. The only indirect signal is that drop in engagement.

The feedback loop

Placement is not the end of the process. Signals flow back from the recipient's mail server to the sender, and how those signals are handled directly affects future deliverability.

Three signals come back:

Bounces. Hard bounces (5xx codes like 550 5.1.1 User Unknown) mean the address is permanently invalid and should be suppressed at once. Soft bounces (4xx codes like 421 Try again later) are temporary and can be retried.
Spam complaints. Relayed through feedback loops when a recipient hits "Report Spam." Above 0.3% deliverability is at serious risk; over 0.1% deserves investigation.
Opens and clicks. Tracked with pixels and redirect links. Image blocking and tools like Apple's Mail Privacy Protection distort the numbers, but a sudden drop on a healthy domain usually means placement has slipped.

FAQ

Does a 200 OK mean my email was delivered?

No. A 200 OK means the message passed validation and was queued for sending. Delivery happens later, when the receiving server accepts the message and returns a 250 over SMTP. Even that is not the same as reaching the inbox, since placement is decided afterward by authentication, reputation, and content filtering.

What is the difference between delivery and deliverability?

Delivery means the receiving server accepted the message; deliverability means it reached the inbox. A 250 confirms delivery, but the receiver still decides whether to file the message in the inbox, in spam, or in a tab like Promotions. A 99% delivery rate can still leave a large share of mail in spam.

Why did my email land in spam with no error?

Spam placement is silent: there is no error code and no webhook when a message is filtered. The message was accepted, so the delivery rate stays high while the open rate drops. That fall in engagement is usually the only signal, which is why tracking opens is the early warning system for placement problems.

What actually decides whether an email reaches the inbox?

Reputation does most of the work, with authentication as the entry requirement. SPF, DKIM, and DMARC have to pass for the message to be considered at all, but the sending domain's reputation, built from how recipients engage with its mail, is what determines placement when the content itself is ambiguous.

Bottom line

Between the API call and the inbox, a message passes through DNS resolution, cryptographic verification, reputation scoring, and content analysis, and each step can silently drop or misroute it. The only confirmation a sender gets is a 250 OK, which means the server took the message, not that anyone will see it. Authentication, reputation, and feedback loops feed into one another, and placement is the result.

Lettr surfaces every step in delivery logs and analytics, on a multi-region email channel built for it, so DKIM alignment and feedback-loop handling are not something to run yourself. Create a free account to send on it.