KoltrixSMTP relay vs HTTP API: how should your app send email?
SMTP relays are universally compatible; HTTP APIs are easier to make idempotent and observable. Compare them on errors, retries, security and speed.
On this page(8 sections)
- How each one works
- SMTP relay
- HTTP API
- Compared side by side
- Where SMTP wins
- Existing software
- Portability
- Full control over the message
- Where HTTP APIs win
- Safer retries
- Clearer errors
- Immediate message IDs
- Fewer moving parts in your code
- Performance and connection handling
- Security considerations
- A decision guide
- Key takeaways
Most email providers offer two doors into the same sending pipeline: an SMTP relay that any mail library can talk to, and an HTTP API designed for application code. Both deliver the same messages.
They differ in how errors surface, how retries work, and how much your code needs to know about email.
How each one works
SMTP relay
Your application connects to the provider's SMTP server, authenticates, and submits a fully formed MIME message:
EHLO app.example.com
AUTH PLAIN ...
MAIL FROM:<[email protected]>
RCPT TO:<[email protected]>
DATA
From: Example <[email protected]>
To: [email protected]
Subject: Your report is ready
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Your weekly report is ready.
.The relay replies with an SMTP status code, typically 250 once the message is accepted for delivery. Your application, or its mail library, is responsible for building the MIME structure, encoding headers, and handling attachments.
HTTP API
Your application sends JSON describing the message, and the provider builds the MIME:
POST /v1/emails
Authorization: Bearer <key>
Content-Type: application/json
{"from": "[email protected]", "to": ["[email protected]"],
"subject": "Your report is ready", "body_text": "Your weekly report is ready."}The provider replies with an HTTP status and a JSON body containing a message ID or a structured error.
Compared side by side
| Concern | SMTP relay | HTTP API |
|---|---|---|
| Compatibility | Works with almost any software that sends mail | Needs code written for that provider |
| Message construction | Your code builds MIME | Provider builds MIME from fields |
| Error detail | SMTP codes and free-text replies | Structured JSON errors with field names |
| Idempotency | No standard mechanism | Often supported via an idempotency key header |
| Message ID for tracking | Usually only in logs or headers | Returned directly in the response |
| Connection overhead | TCP, TLS, auth and a multi-step dialogue per session | One HTTPS request; connection reuse via keep-alive |
| Firewall issues | Outbound SMTP ports sometimes blocked | HTTPS port 443 almost always open |
| Batch sending | Multiple RCPT TO per transaction | Varies; often a batch endpoint |
| Vendor lock-in | Low; swap host and credentials | Higher; payload shapes differ |
Where SMTP wins
Existing software
Content management systems, monitoring tools, ticketing systems, network devices and legacy applications often support only SMTP. For them, a relay is the only option, and it lets them benefit from your provider's authentication, suppression and tracking without code changes.
Portability
SMTP is a standard. Moving from one provider to another is a configuration change: new hostname, new credentials. That makes it attractive for teams that want to keep their options open, or that route mail through different providers for different purposes.
Full control over the message
If you need precise control over MIME structure, unusual headers or exactly-formed messages, building the MIME yourself and submitting it over SMTP gives you that control. Many HTTP APIs also accept raw MIME, so this is not unique to SMTP, but it is native to it.
Where HTTP APIs win
Safer retries
This is the biggest practical difference. If an HTTP request times out, you can retry with the same idempotency key and the provider will not send twice. SMTP has no standard equivalent. If the connection drops after you send the final . of DATA but before you receive the 250, you cannot know whether the message was accepted. Retrying risks a duplicate; not retrying risks loss. The SMTP specifications have long acknowledged this window, and it is inherent to the protocol.
Clearer errors
An API can tell you "field": "from", "code": "sender_not_verified". An SMTP relay tells you something like 553 5.7.1 Sender address rejected, with wording that varies by provider. Structured errors are easier to handle programmatically and easier to surface to developers.
Immediate message IDs
APIs return an ID you can store with your business record and later match against webhook events. With SMTP, you can set your own Message-ID header, but correlating it with the provider's internal ID often depends on how the provider exposes it.
Fewer moving parts in your code
No MIME library, no header encoding, no line length concerns. For simple transactional messages, the JSON request is shorter and harder to get wrong.
Performance and connection handling
A single SMTP session involves several round trips: greeting, EHLO, STARTTLS or a TLS handshake, authentication, then MAIL, RCPT and DATA for each message. Reusing one SMTP connection for many messages amortizes the setup cost, and many libraries support connection pooling. HTTP APIs with keep-alive connections behave similarly. In practice, for most applications, neither is a bottleneck; the provider's queue and the recipient's servers dominate end-to-end time.
Security considerations
Both doors deserve the same care with credentials. An SMTP relay password, or an API key used as one, can send mail as your domain just like an API key can. Prefer providers that let you use a scoped, revocable key for SMTP authentication rather than an account password, require TLS on the submission connection, and give each application or tool its own credential so one leak does not force you to rotate everything.
A decision guide
- Writing new application code? Use the HTTP API, mainly for idempotent retries and structured errors.
- Connecting off-the-shelf software? Use the SMTP relay.
- Need portability across providers above all? SMTP, or an internal abstraction over provider APIs.
- Sending complex MIME you build yourself? SMTP, or an API endpoint that accepts raw MIME.
- Running in an environment that blocks SMTP ports? HTTP API, or a relay on an alternative submission port.
Many teams use both: the API for their own application and the relay for third-party tools, all flowing through the same provider account, suppression list and webhooks. Koltrix, for example, offers a REST endpoint and an SMTP relay that feed the same sending pipeline.
Key takeaways
- SMTP relays offer universal compatibility and easy provider switching.
- HTTP APIs offer idempotent retries, structured errors and immediate message IDs.
- SMTP has an unavoidable ambiguity when a connection drops after DATA, which can cause duplicates on retry.
- Prefer the API for new code and the relay for software that only speaks SMTP.
Start with Koltrix
Your domain, one inbox, and an API that sends.
A team inbox where AI sorts and drafts (nothing is sent without your click), plus the transactional API and SMTP relay your product sends with. 7 days free, no card.
