How system email works

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.
Public key — what authorises your own code to send. It is a platform credential rather than a Mail one: a product Owner or Admin creates it in the workspace, under the product’s Settings → Public Access, and scopes it to the public routes it may call — every route of the product, every route of one toolkit, or exactly one route such as POST /emails. A scope names routes, not sending domains, so a key that may send may send from any verified domain of the product. A key created today starts with lpk_, and one the platform imported from Mail’s older sending keys keeps its lmk_ prefix and its original value and works the same way. The secret is shown once, at creation, and never again. See authenticate the public API.
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 4 configure Mail and happen inside your product, under Mail → Domains, or against the same product-authenticated API that screen uses. Step 5 happens in the workspace, one level above the toolkit. Steps 6 and 7 happen from your own application code, over Mail’s public sending endpoint, and are the only ones that use the public 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. Mail → Domains → Add domain opens the same list: its Domain dropdown holds exactly these apexes, and it tells you when there are none. See set up a sending domain.
Register the domain. A dedicated subdomain such as mail.example.com is the usual choice, because it keeps your product’s mail apart from the mail your team sends by hand. The response comes back pending, with the DNS records to publish and the domain’s id. In the Add domain dialog: send from the apex itself, or choose Add a subdomain and type the prefix — the dialog shows you the sending domain it will register.
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. The same records are the DNS records to publish table on Mail → Domains → <domain>, which also marks the recommended ones.
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 — Mail → Domains → <domain> shows the status, refreshes itself every few seconds while verification is pending, and Verify now runs the check on the spot. Until the domain is verified, a send from an address at it fails with 422 invalid_from_address.
Create a public key. A product Owner or Admin creates it in the workspace, under the product’s Settings → Public Access, and scopes it to the one route your application calls — POST /emails on Mail — rather than to everything in the product. The lpk_… secret is shown once, on the screen that creates it, so store it as you create it, and give it about thirty seconds before you use it. Already holding a Mail API key? Do not create a new one: keys beginning lmk_ were imported into the product’s key list and go on working. See authenticate the public API.
Send the message from your application, with the key as a bearer token in the Authorization header and a from address 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. Mail → Logs carries the same answer and Mail → Logs → <email> adds the events the message went through; Mail → Emails → Look up status reads one back by its id. 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 failed and 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.

Where Mail sits in the workspace

Lessly Mail is the Mail entry in the product’s navigation, and the screens under it follow the model above.

Screen	What it answers
Mail	The dashboard: how much you have sent lately and how much of it arrived.
Mail → Domains	The domains you have registered, and the dialog that registers another.
Mail → Domains → <domain>	One domain: the DNS records to publish, the status they add up to, and a re-check you can run on the spot.
Mail → Emails	Sending one message by hand, and finding out what became of a message you already sent.
Mail → Logs	Every message the product has sent, narrowed by recipient, domain or status.
Mail → Logs → <email>	One message and the events it went through, in order.
Mail → Suppressions	The list of addresses nothing is ever sent to.

One screen you need sits outside Mail. The public key your code sends with is created in the workspace, under the product’s Settings → Public Access, because it is a platform credential that can cover the public routes of any toolkit in the product. That is also where a key is rescoped and revoked. Mail also issues a sending key of its own, for its own API — a different key, covered in authenticate the public API.

Templates, contacts, audiences, broadcasts, webhooks and the reputation report have no screen at all. The page that covers each names the tool that performs the action instead.

Next steps

Set up a sending domain: register a domain, publish its DNS records, get it to verified.
Authenticate the public API: where the public key comes from, what its scope covers, and how to replace one.
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.

Was this page helpful?