How system email works
What Lessly Mail sends on your product's behalf — confirmations, invitations, access recovery, receipts — and the seven steps from an empty setup to a delivered message.
System email is the mail your product has to send in order to work at all: the message that confirms an address, the one that invites a colleague, the one that lets someone back into an account they are locked out of, and the receipt for what they paid. Each goes to one person, at an address they gave you, because of something they just did — and each is expected, which is why it has to arrive.
Lessly Mail sends those messages for you. You add a domain you own, publish the DNS records it asks for, and from then on every message keeps a status you can read back and an outcome you can be notified about.
What you work with
- Product — the boundary of everything Mail does for you. Every domain, key, template, suppression and webhook belongs to exactly one product and is invisible from another. The product itself is a platform concept, managed there rather than here. See the Lessly platform model.
- Domain — what makes sending possible. You add a domain you control, publish the records Mail returns, and nothing can be sent from an address at it until it is
verified. See set up a sending domain. - API key — what authorises your own code to send. A key is scoped
sending_accessorfull_access, may be locked to a single domain, and starts withlmk_; the secret is shown once, at creation, and never again. See create and rotate a sending key. - Email — one message to one or more recipients, written inline or rendered from a published template, carrying subject, bodies, cc, bcc, reply-to, custom headers and your own tags. See send a message.
From nothing to a delivered message
Steps 1 to 5 are setup and happen once, against your product’s authenticated session. Steps 6 and 7 happen from your own application code, and are the only ones that use a Mail API key.
- Find the domains you may send from. Mail sends only from a domain your product already owns — the apexes available to you, or any subdomain of one. See set up a sending domain.
- Register the domain. A dedicated subdomain such as
mail.example.comis the usual choice, because it keeps your product’s mail apart from the mail your team sends by hand. The response comes backpending, with the DNS records to publish and the domain’s id. - Publish the DNS records at your own DNS provider, exactly as returned — values included. The DKIM records are required; the DMARC record is not, but publishing it is recommended.
- Wait for the domain to verify. Mail re-checks every unsettled domain once a minute on its own, so publishing the records is all you have to do. You can ask for an immediate check instead of waiting.
- Create an API key with the
sending_accessscope, locked to the domain from step 2. The secret appears in that one response and nowhere else, so store it as you create it. See create and rotate a sending key. - Send the message from your application, with the key in the
X-Api-Keyheader and afromaddress at the verified domain. See send a message or send from TypeScript. - Read what happened to it. The identifier you got back means accepted, not delivered. Being told beats asking: see receive delivery events.
How long step 4 takes is your DNS provider’s decision, not Mail’s — usually a few minutes, sometimes several hours. Mail keeps trying for 72 hours; past that the domain becomes
failedand has to be registered again.
What happens to a message
Creating an email does not deliver it. The message is accepted, given an identifier and queued; from there its status is the record of what the receiving mail servers did with it.
| Status | Meaning |
|---|---|
scheduled | Accepted and waiting for its send time. Can still be rescheduled or cancelled. |
queued | Accepted and about to be handed to the receiving mail servers. |
sent | Handed over. The receiving server has not reported an outcome yet. |
delivered | The receiving server accepted the message for its recipient. |
bounced | The receiving server rejected it. |
complained | The recipient marked it as spam. |
suppressed | Every recipient was on your suppression list, so nothing was sent. |
blocked | A sending limit or your sender reputation stopped it before it went out. |
failed | The message could not be handed over. |
canceled | You cancelled it before it went out. |
Two outcomes feed back into later sends. A hard bounce or a spam complaint adds that recipient to the product’s suppression list, and it is skipped from then on. And your rates of hard bounces and complaints over a rolling window make up your sender reputation: if either crosses its threshold, sending is throttled until the rate recovers. See handle bounces and protect your sending.
Transactional email and marketing broadcasts
Mail sends two kinds of message, and the difference decides which rules apply.
| Transactional | Broadcast | |
|---|---|---|
| Addressed to | A specific person, because of something they did | Everyone in an audience |
| Prior consent | Not required — the recipient asked for the thing this message is about | Required |
| Created by | Sending directly, to addresses you supply | Drafting, then queueing, which fans out into one message per eligible contact |
| One-click unsubscribe header | No | Yes, on every message |
| Suppression list | Applies | Applies, and unsubscribed contacts are skipped as well |
| Progress reported | Per message | Per message and for the broadcast as a whole |
Everything on these pages is transactional. Marketing broadcasts are documented separately — see send a broadcast.
Next steps
- Set up a sending domain: register a domain, publish its DNS records, get it to
verified. - Create and rotate a sending key: scope a key, lock it to one domain, replace it without downtime.
- Send a message: the fields a send accepts, batches, scheduling and the limits.
- Receive delivery events: be told what happened instead of polling for it.
- Handle bounces and protect your sending: the suppression list, and the rates that throttle you.