@flui-cloud/mail

Transactional email that actually arrives — over any provider, without running a mail server.

npm install @flui-cloud/mail

TypeScript, strict · Apache-2.0

The problem

Sending mail from an application is two problems wearing one hat.

The first — handing a message to a provider — is a single HTTP call. The second — getting receivers to believe the message is yours — is SPF, DKIM and DMARC, and it is where almost everyone's mail quietly ends up in spam.

Quietly is the operative word. Mail fails silently: nothing throws, nobody is told, and the password reset simply never arrives.

This package does the first over whatever provider you like, and takes the second seriously.

Why not just run a mail server

Because the reputation problem has no local solution. Most cloud hosts block outbound SMTP ports on new instances by default, and a fresh address range has no sending history for receivers to trust. Running your own MTA means earning that trust from zero and being able to lose it to a single misconfiguration.

So this package never installs one. It authenticates your domain and relays through a provider whose reputation already exists — then watches whether the mail is actually landing.

Who it is for

Anyone sending transactional mail from their own infrastructure who wants to know whether it arrived — and who does not want a mail server, a vendor lock-in, or a bill that starts before the first message.

It was built for two deliberately different consumers: a local-first CLI running on someone's laptop, and a hosted multi-tenant platform. So the core assumes no filesystem, no database and no public URL. Anything host-specific enters through a seam you implement.

What you get

• Any provider. Everything is normalised to one three-member interface, and anything that speaks SMTP — which is all of them — needs no driver at all. Nothing here decides which providers are allowed to exist.
• The deliverability records, correctly. A domain may publish exactly one SPF record, so a new sender is merged into it rather than added beside it — and merged before the all mechanism, because a term written after it authorises nothing while looking exactly as though it did.
• Verification that reads DNS, not the zone API. What your zone file says and what the world resolves differ while a change propagates, and only the second decides whether mail authenticates.
• Bounce and complaint handling that errs on the safe side. A permanent refusal suppresses an address; a temporary one never does. Greylisting is designed to look like a failure the first time, and a wasted retry is far cheaper than silently cutting off someone whose mail was fine.
• Delivery outcomes, polled or pushed. Same seam, opposite direction — which is what lets a client with no public address still report what happened.

Built in

Three API drivers ship in the box alongside the generic SMTP relay. None is privileged: they are defaults, not the architecture, and swapping one out is a constructor argument rather than a migration.

Each also declares what it can find out after a message leaves — see MailObservability. It is required rather than optional for the same reason MailCapabilities is: a console that computes a delivery rate over a provider which never reports deliveries shows 0% forever, and condemns a healthy relay on the absence of evidence.

Metadata only

Recipient, timing, verdict, provider reason — and the subject line, because a log that cannot tell an invitation from a password reset is not worth consulting.

Message bodies are never carried and never stored. This is a control plane for sending, not a mailbox, and it stays on the right side of that line deliberately.

Runtime

The package index has no node: imports and stays importable from a browser bundle. Anything needing a Node runtime lives behind @flui-cloud/mail/node.

Documentation

• Project README — the full argument
• Choosing a provider — what ships in the box, and what to look for in anything else
• Adding a provider — an SMTP relay in about twenty lines, an HTTP API in thirty

Fuller usage documentation is coming.

License

Apache-2.0