What Actually Happens When You Send an Email Through an API?
Most developers think sending an email looks like this:
POST /send-email
Pass the recipient, subject, HTML, and a few other fields.
Get a 200 OK.
Done.
But that API request is only the beginning.
Behind that simple endpoint is an entire delivery pipeline involving queues, validation, authentication, retries, SMTP, DNS, reputation, bounce handling, observability, and failure recovery.
This is one of the problems we are solving at Senviok.
The journey of an email
A simplified version of the architecture looks like this:
Your Application
|
v
Senviok API
|
v
Validation
|
v
Message Queue
|
v
Delivery Workers
|
v
SMTP / Mail Infrastructure
|
v
Recipient Mail Server
|
v
Inbox
The interesting part is everything that happens between those boxes.
1. Your application makes the request
A developer might make a request like:
POST /v1/emails
with information such as:
{
"from": "hello@example.com",
"to": "user@example.com",
"subject": "Verify your account",
"html": "<h1>Your verification code is 482931</h1>"
}
At this point, the email has not been delivered.
We've only received an instruction to deliver it.
That distinction is important.
2. The API validates the request
Before anything gets sent, the infrastructure needs to determine whether the request is valid.
Things like:
- Is the API key valid?
- Is the sender authorized?
- Is the recipient address valid?
- Does this tenant have permission to use this domain?
- Has the tenant exceeded its rate limit?
- Is the payload valid?
- Does the request contain the required fields?
You don't want invalid messages reaching the delivery layer.
3. The message enters a queue
This is where things start getting interesting.
You generally don't want your API request to sit there waiting for an external mail server to respond.
Instead:
API
|
v
Queue
|
v
Worker
The API accepts the message and the delivery system processes it asynchronously.
This gives the system room to handle traffic spikes without making every application request depend directly on the speed of downstream mail servers.
4. The worker handles delivery
A worker picks the message from the queue and attempts delivery.
But delivery isn't always successful.
The recipient's mail server could:
- temporarily reject the message
- permanently reject the address
- throttle the connection
- time out
- return a temporary SMTP error
- accept the message
That means the delivery system needs to understand SMTP responses and decide what happens next.
A temporary failure might result in a retry.
A permanent failure should generally result in a bounce.
5. Retries are not as simple as retrying
Imagine the recipient's mail server is temporarily unavailable.
You retry.
It fails again.
You retry immediately.
It fails again.
Now you're potentially hammering a server that is already telling you it cannot accept your messages.
This is where retry policies become important.
A delivery system needs to think about things like:
Attempt 1
|
v
Failure
|
v
Wait
|
v
Attempt 2
|
v
Failure
|
v
Wait longer
|
v
Attempt 3
Exponential backoff, retry limits, queue visibility, dead-letter handling, and failure classification all become part of the system.
6. Then there is deliverability
Successfully handing a message to a mail server doesn't necessarily mean it reaches the inbox.
Email providers evaluate many signals.
Your domain needs proper authentication.
That includes mechanisms such as:
- SPF
- DKIM
- DMARC
And then there is reputation.
A sender with poor reputation can have perfectly valid SMTP communication and still have messages rejected, throttled, or placed in spam.
This is one of the reasons email infrastructure is much more complicated than simply exposing an SMTP connection through an API.
7. You also need observability
Imagine a customer says:
"My verification email never arrived."
The infrastructure needs to answer:
- Did we receive the request?
- Was the request accepted?
- Was the message queued?
- Was it processed?
- Did delivery begin?
- What did the recipient server respond with?
- Was the message rejected?
- Was it deferred?
- Was it eventually delivered?
Without proper event tracking and observability, debugging becomes guesswork.
A production email infrastructure therefore needs visibility across the entire message lifecycle.
Accepted
↓
Queued
↓
Processing
↓
Attempted
↓
Delivered / Deferred / Bounced
8. Then comes scale
Sending 10 emails is easy.
Sending 10,000 emails introduces another class of problems.
Sending millions introduces an entirely different system.
You have to think about:
- queue throughput
- worker concurrency
- connection management
- rate limits
- tenant isolation
- database performance
- backpressure
- horizontal scaling
- monitoring
- failure recovery
And suddenly that tiny POST /send-email endpoint represents a much larger distributed system.
Why we're building Senviok
This is the engineering problem behind Senviok.
We want developers to have a simple interface for sending communication without having to build and operate the underlying delivery infrastructure themselves.
The developer should be able to think about:
send(email)
while the infrastructure handles the complexity underneath.
That's the interesting part of building developer infrastructure.
The API can be simple.
The system behind it shouldn't be.
And that's exactly where the engineering challenge begins.
Top comments (2)
senviok is the best email api provider
One item in the step-2 list belongs one box lower: recipient validity is not decidable at API time. Syntax and an MX lookup are all that is available there, and neither answers whether the mailbox exists - that only comes from the recipient server's
RCPT TOreply, and providers that accept-then-bounce make even that non-authoritative. So it is a classification for step 4 rather than a gate for step 2, and the placement matters because the cost is asymmetric: a wrongly rejected verification email is the one failure a transactional sender cannot retry its way out of, since the instruction never entered the pipeline that step 1 is careful to separate from delivery.