Sending
Transactional email
Transactional email is mail an application sends to one recipient because of something that recipient did or that happened to their account — a receipt, a password reset, a shipping notice, an alert.
It is the opposite of marketing email: expected, individually triggered, and often legally or operationally important. That importance is why transactional mail deserves a delivery record — when a password reset "never arrived", someone has to be able to look. Mailway is built for exactly this class of mail.
SMTP relay
An SMTP relay is a server that accepts email from your application over the standard SMTP protocol and forwards it toward its destination, so the application doesn't deliver mail itself.
Because SMTP is a universal standard, adopting a relay is a configuration change — host, port, credentials — not a code change. Anything that ships mail today (Nodemailer, Laravel, Rails, smtplib) already speaks it. Mailway's relay listens on seven ports with TLS on every one; the quickstart gets a real send through it in about ten minutes.
Email gateway
An email gateway is a layer between an application and its email providers: the app hands each message to one endpoint, and the gateway decides which provider carries it, retries when one fails, and keeps the record.
A gateway is not a provider — it doesn't operate sending infrastructure of its own. It adds what individual providers can't: failover across them, one normalized delivery history, and an archive that outlives any single account. Mailway is an email gateway.
Email service provider (ESP)
An email service provider is a company that operates sending infrastructure — IP pools, reputation management, delivery to mailbox operators — and sells it as a service: Amazon SES, SendGrid, Mailgun, Postmark, and their peers.
Providers differ in pricing, free tiers, rate limits, and how they report delivery outcomes — and any one of them can time out, rate-limit, or suspend an account. Under Mailway's BYOK model you keep your own provider accounts and Mailway routes across them, instead of replacing them.
BYOK (bring your own keys)
BYOK — bring your own keys — means you connect your own email provider accounts and the gateway sends through them with your credentials, rather than through infrastructure the gateway owns.
The consequences are structural: delivery is billed by your providers at their prices (Mailway never adds a per-email margin), sender reputation stays attached to your accounts, and domain authentication lives on your DNS at your provider — see the provider guides. The trade: you manage provider accounts; in exchange, no lock-in and no middleman on price.
Routing
Provider failover
Provider failover is automatic rerouting: when an email provider fails to accept a message — a timeout, a rate limit, an exhausted account — the gateway reads the error and hands the message to the next provider in the chain, mid-send.
Done right, failover is selective: a hard bounce is a fact about the address, not the provider, so it is suppressed rather than retried through the next door. Mailway classifies each failure before deciding — how routing and failover work.
Routing strategy
A routing strategy is the policy that picks which provider carries each message when more than one is connected.
Mailway ships four, set per project: failover (a fixed order, next on error), free-first (spend free tiers before paid volume), round-robin (rotate evenly), and random. Whatever the strategy, a failed attempt still falls through to the remaining providers — the strategy chooses the first door, not the only one.
Free-first routing
Free-first routing sends each message through whichever connected provider still has free-tier quota left, so paid volume starts only after the free allowances are spent.
Most providers include one — Amazon SES, Mailgun, SendGrid and others each give away a monthly allowance that single-provider setups can't combine. Free-first pools them. Deliverability still outranks cost: a provider whose free tier is exhausted remains a failover target. The calculator on the failover page shows the effect on a monthly bill.
Delivery truth
250 OK (provider accept)
250 OK is the SMTP success code a server answers when it takes responsibility for a message — it means the handoff succeeded, not that the email reached anyone.
Between a provider's 250 OK and an inbox sit reputation checks, spam filtering, greylisting, and the recipient server's own decisions. Treating 250 OK as "delivered" is the most common honesty failure in email dashboards; Mailway labels the number it shows you — see accepted vs delivered.
Accepted vs delivered
Accepted means a provider took the handoff of a message; delivered means the recipient's mail server took final delivery — and the two are different facts, learned at different times, from different sources.
Acceptance is synchronous (the 250 OK); delivery is asynchronous, reported later through delivery events — and only for providers that send them. A dashboard that shows one number without saying which is showing an accept rate dressed as a delivery rate. Mailway keeps the two apart everywhere, including in proof-of-delivery certificates, which state their claim level explicitly.
Delivery event
A delivery event is an asynchronous report from an email provider about what happened to a message after it was accepted: delivered, bounced, or marked as spam.
Events arrive minutes or hours after the send, over provider webhooks. Because every provider reports back into the same gateway, Mailway normalizes them into one delivery history — an SES bounce and a Mailtrap bounce read the same — and each event lands on its message's timeline and can be forwarded to your app as a signed webhook. See the webhooks reference.
Hard bounce
A hard bounce is a permanent delivery failure: the address doesn't exist, the domain has no mail server, or the recipient's server refused the message categorically.
Hard bounces must not be retried — sending again to a dead address damages sender reputation, and mailbox operators track exactly that. The correct response is to record the fact once and stop, which is what a suppression list is for. Mailway stamps hard bounces from both synchronous rejections and asynchronous delivery events.
Soft bounce
A soft bounce is a temporary delivery failure — a full mailbox, a greylisting deferral, a server that's briefly down — that is expected to succeed on retry.
The soft/hard distinction is the whole game in bounce handling: soft failures are retried, permanent ones are suppressed. Providers encode the difference inconsistently, which is one reason a gateway normalizing their events into one vocabulary is useful.
Spam complaint
A spam complaint is a recipient pressing the “mark as spam” button, reported back to the sender through a mailbox provider's feedback loop.
Complaints are the strongest negative signal a sender can accumulate — mailbox operators throttle or block senders whose complaint rate crosses fractions of a percent. A complained address should never be mailed again; Mailway records the event on the message timeline and adds the address to the suppression list.
Suppression list
A suppression list is the set of addresses a sender must not mail — hard bounces, spam complainers, manual additions — checked before every send.
The list matters because reputation damage is repeatable: every send to a dead or complaining address costs again. In Mailway the list is checked at send time regardless of which provider would carry the message, so a hard bounce learned through one provider gates all of them. Lists are managed per project — the suppressions reference.
Authentication
SPF
SPF (Sender Policy Framework) is a DNS record listing the servers allowed to send email for a domain; receiving servers check the connecting IP against it.
SPF authenticates the envelope sender, not the From header a person reads — which is why it needs DMARC on top. Under BYOK, the record lives on your DNS and names your provider's servers; Mailway never appears in it, because your provider does the delivering. The deliverability guide walks the records.
DKIM
DKIM (DomainKeys Identified Mail) is a cryptographic signature a sending server adds to a message, verifiable against a public key published in the sender's DNS.
A valid signature proves the message content wasn't altered in transit and that the signing domain vouches for it. Mailway relays byte-for-byte, which keeps the original signature intact in the archive — and validates it on the stored copy, an integrity proof that doesn't require trusting Mailway.
DKIM alignment
DKIM alignment means the domain that signed a message (the d= in the DKIM signature) matches the domain in the From header the recipient sees.
A signature can be valid yet unaligned — a provider signing with its own domain proves the mail passed through the provider, not that your domain sent it. DMARC only passes on aligned signatures, which is why "we have DKIM" and "we pass DMARC" are different statements. Alignment is configured at the provider, on your DNS — see deliverability.
DMARC
DMARC is the policy layer over SPF and DKIM: a DNS record that tells receiving servers what to do with mail from your domain that fails aligned authentication — monitor it, quarantine it, or reject it.
DMARC is what actually stops others from sending as your domain, and mailbox operators increasingly require a policy for bulk senders. It also sends aggregate reports, which are how you discover what's sending as you. Start at p=none (monitor), tighten once the reports are clean — the sequence is in the deliverability guide.
Protocol & API
Envelope vs headers
The SMTP envelope (MAIL FROM, RCPT TO) is the addressing the servers use to route a message; the headers (From:, To:, Cc:) are the addressing people read — and the two can legitimately differ.
Bcc works only because of this split: the recipient is in the envelope but deliberately absent from the headers. The distinction has sharp edges — Amazon SES counts the union of envelope and header recipients against its 50-recipient cap, which is why naive chunking of a large send fails. Mailway's handling of that exact case is documented in the SMTP reference.
STARTTLS vs implicit TLS
STARTTLS upgrades a plaintext SMTP connection to encrypted mid-session (ports 587, 2525); implicit TLS is encrypted from the first byte (port 465).
Both end encrypted, and both are fine — what matters is refusing to authenticate before encryption exists, so credentials never cross the wire in the clear. Mailway's submission ports require STARTTLS before AUTH, and 465/2465 speak implicit TLS; the full port matrix is on the developers page.
Idempotency key
An idempotency key is a client-chosen token attached to an API request so that retrying the same request — after a timeout, a crash, a network error — performs the operation once instead of twice.
For email the duplicate isn't an invoice paid twice, but it is a customer emailed twice, which erodes trust in every future message. With Mailway's send API, a retried request carrying the same key returns the original send's response instead of creating a new mail.
Signed webhook
A signed webhook is an HTTP callback whose payload carries a cryptographic signature (typically HMAC over the body and a timestamp), so the receiver can verify who sent it and that it wasn't altered.
An unsigned webhook endpoint accepts events from anyone who finds the URL. Mailway signs every delivery Stripe-style and retries failures on a backoff ladder; consumers verify the signature and deduplicate, since delivery is at-least-once. Setup and verification code are in the webhooks reference.
Email sandbox
An email sandbox accepts and records messages exactly like production but delivers nothing, so development and staging can send freely without a real person ever receiving a test.
The classic failure it prevents: a staging batch job mails real customers. Mailway's sandbox is the same relay at a different hostname — smtp.mailway.dev, same credentials — and captured mail gets the full timeline and archive treatment, so what you inspect in development is what production will record. See the sandbox docs.
The record
Byte-for-byte relay
A byte-for-byte relay forwards a message exactly as the sender submitted it — no link rewriting, no tracking pixels, no header cleanup — so the delivered mail and the archived mail are the same bytes.
Fidelity is what keeps the original DKIM signature verifiable years later, which is what makes an archive provable rather than merely stored. Mailway holds this with exactly one documented exception (recipient-header handling above a provider's recipient cap, which leaves the body and its DKIM body hash untouched) — the stance is spelled out in the SMTP reference.
Email archive
An email archive is a durable, searchable copy of every message an application sent — bodies, headers, attachments — kept independently of the provider that delivered it.
Providers retain little (often 3–30 days of metadata, rarely full content), and the retention vanishes with the account. An archive answers the questions that arrive months later: what exactly did we send this customer, and can we prove it. Mailway archives every message as submitted, searchable like a mailbox, with retention set by plan — the retention windows.
Proof of delivery (email notary)
Proof of delivery for email is a signed certificate binding together what was sent (a content hash and the original DKIM signature), when a provider accepted it, and what the provider later reported — verifiable by a third party without trusting the platform that issued it.
The point is disputes: "we never received it" against "we sent it" is memory against memory unless someone kept evidence. Mailway's certificates are Ed25519-signed with an RFC 3161 timestamp, verify offline, and state their claim level honestly — accepted and delivered are separate claims. How verification works.
Delivery history
A delivery history is the per-recipient record of outcomes — accepted, delivered, bounced, complained — accumulated across every message sent to that address.
Its value compounds when it spans providers: any single provider sees only its own attempts, but a gateway sees them all, normalized into one vocabulary. That is the vantage point that makes cross-provider comparisons and suppression decisions trustworthy — a bounce learned through one provider is knowledge applied to all of them. It's the backbone of Mailway's observability.