Transactional Email — send as your app
Your Host app sends its own receipts, resets and notifications. Each app has one sending address, and each accepted send is charged in credits to the Solution that owns the app.
Send without any setup
waymaker host email send <app_id> \
--to someone@example.com \
--subject "Your booking is confirmed" \
--text "See you Tuesday at 10am." \
--from bookings
If the app has no sending address yet, the first send gives it one on a domain Waymaker owns:
"<App name>" <bookings@{app-slug}.{org-slug}.waymakermail.com>
You don't need DNS, a domain or a key. The display name is the app's name. --from sets only the
part before the @; the domain is always the app's own, so one app can't send as another.
To see the address before the first send:
waymaker host email domain register <app_id> # no domain = shows the ready-made address
Nothing is created until the app's first send. The response has planned: true and the expected
address. After the first send, domain list shows it:
waymaker host email domain list --app <app_id> --json
Choose before the first send. An app has one sending address at a time. The ready-made address is created on the app's first send, and that includes the first sign-in email if the app uses Host sign-in (see below). If the app should send as your own domain, register it before anything is sent.
To change it later, an org admin who owns the app's Solution removes the current one and registers the new one in the same step:
waymaker host email domain remove <domain_id> --confirm <current-domain> --replace-with mail.example.com
This takes about 15 seconds. The old domain is released, but its send history and billing stay.
Until the new domain verifies, the app's sign-in emails come from Waymaker's no-reply address
("<App name> via Waymaker"), and its other sends wait. Without --replace-with, the app's next
email creates the ready-made address again (the same name). If removal reports that a step couldn't
finish, nothing is sent from the old domain; run the same command again.
kind is default for a ready-made address and custom for your own domain. A brand-new address
can report pending for a minute while its records propagate. The next send or verify checks
again.
Send from your own domain (optional)
waymaker host email domain register <app_id> mail.acme.com
The response's dns_records lists CNAME records only, and each one points at a Waymaker
hostname. Add them at the domain's DNS provider, then:
waymaker host email domain verify <domain_id>
Pick a subdomain the domain doesn't already send mail from, so the records can't clash with existing
mail. Each record carries its own status, so you can tell which one is still missing.
Sign-in emails
If the app uses Host sign-in, its sign-in codes, password-reset codes and verification links are
sent from the app's own address too: "<App name>" <noreply@{app-slug}.{org-slug}.waymakermail.com>,
or noreply@ your own domain once it is verified. They use a branded layout with the app's name.
Set the name and logo yourself. The logo is a file in Storage, not a link: put a PNG or JPEG of at most 100 KB (email clients don't show SVG) in a public bucket in the app's Solution, then:
waymaker host db auth email-brand <app> --name "Acme Portal"
waymaker host db auth email-brand <app> --logo-bucket <bucket> --logo-key brand/logo.png
waymaker host db auth email-brand <app> # shows what the emails use now
waymaker host db auth email-brand <app> --clear logo # or: name, all
It takes effect from the next email, with no redeploy. The logo travels inside each email rather
than as a link, so mail clients show it straight away, even to a recipient who hasn't seen the sender
before. A larger file is refused when you set it. If the bucket later stops being public, leaves the
Solution or is deleted, the emails go out without a logo; email-brand <app> says so.
The app's first sign-in email creates its address, which takes a few minutes to verify. Until then,
and whenever the app's address can't send one (it is paused, being replaced, or the recipient bounced
before), that email comes from Waymaker's no-reply address as "<App name> via Waymaker", so nobody
is locked out.
Delivering into Microsoft 365 and Google Workspace
If the people signing in to the app use a company mailbox, their mail system decides how the email looks when it arrives:
- Outlook's "from outside your organisation" banner is added by the recipient's Microsoft 365 tenant to mail that arrives from outside it. The sending side can't remove it, and a sender on a subdomain of the company's own domain doesn't remove it either unless the tenant trusts that sender.
- To make an internal tool's email look internal, the company's Microsoft 365 admin adds the app's sending address as an allowed sender, or a mail-flow (transport) rule that skips the external tag for that sender when SPF and DKIM pass. In Google Workspace, the admin adds an approved-sender rule in Gmail settings.
- Sending from your own subdomain (for example
mail.example.com) means registering it and adding its CNAME records. It signs the mail with your domain, but on its own it doesn't remove the banner. - The logo travels inside the email, so it shows without "Show blocked content", even from a sender the recipient hasn't seen before.
Sending health
waymaker host email health <app_id> [--json]
This returns:
daily: sends and outcomes per day (delivered,hard_bounced,soft_bounced,complained,delayed);window: the 7-day bounce and complaint rates and thevolumethey're measured over;limits: the rates that pause sending automatically;sending_enabled,paused_atandpaused_reason;suppressed_recipients.
Automatic pause. Sending is paused when hard bounces reach 4%, or spam complaints reach
0.1% of delivered mail, over 7 days. It applies only after at least 100 messages, and only when
at least 2 such events have happened. From then on send returns 403. A pause is lifted only by
Waymaker support, never automatically. The rates count from that moment, so the history that caused
the pause doesn't immediately cause another.
Suppression. A hard bounce or a spam complaint stops this app from mailing that address again.
If every recipient of a send is suppressed, send returns 422 and records the attempt with
status: "suppressed". Nothing is sent and nothing is charged. If only some are suppressed, the rest
are sent and the response lists suppressed.
Send from your app's server
Give the app its own sending key. It can send this app's email and read this app's send status and health — nothing else, for no other app — so your server never holds a person's API key.
waymaker host email key create <app_id> # into the app's env as WAYMAKER_EMAIL_KEY; never shown
waymaker host apps deploy <app_id> # the variable reaches the app on its next deploy
Then, from server-side code:
await fetch('https://apps.waymakerone.com/functions/v1/host-transactional-email', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.WAYMAKER_EMAIL_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
action: 'send',
data: { to: 'customer@example.com', subject: 'Your receipt', html: '<p>Thanks!</p>', from_local_part: 'receipts' },
}),
})
app_id may be left out — the key decides it. Any other app, or any action other than send,
send_status and health, answers 404.
| Command | What it does |
|---|---|
key create <app_id> [--env NAME | --show] | One key per app. Into the env by default; --show prints it once instead. |
key rotate <app_id> [--env NAME | --show] | New key; the old one stops working immediately — redeploy the app straight after. |
key revoke <app_id> --confirm | Stops it, and removes it from the env if it was placed there. |
key list <app_id> | Prefix, env variable, created, last used, revoked. Never the key. |
The env variable must be a server-side name: names starting
with _ and browser-bundle prefixes (VITE_, NEXT_PUBLIC_, …) are refused. Creating, rotating
and revoking need the owner or releaser role on the app's Solution (outside a Solution: the app's
creator or an organisation admin).
A key lasts only as long as its creator's access. When the person who created it leaves the
organisation or loses the owner or releaser role, a key that was shown to them (--show) stops
working at its next use. A key that only ever went into the env is rotated at its next use instead:
a new key goes into the same variable, the old one keeps working for 72 hours so the app can
redeploy, and key list shows the old one with its end time in revoked_at. The organisation's
owners are emailed either way.
MCP
The same actions are available as MCP tools: host_email_domain_register (domain is optional),
host_email_domain_list, host_email_domain_get, host_email_domain_verify, host_email_send,
host_email_send_status, host_email_quota and host_email_health. Every response includes full ids.
host_email_key_create, host_email_key_rotate, host_email_key_revoke and host_email_key_list
manage the sending key; through MCP the key always goes into the app's env and is never returned.
Limits
| Limit | What happens |
|---|---|
| Daily ramp | A new address can send 100 on its first day, doubling each day up to 10,000. Over the limit, send returns 429 with the current cap. |
| Rate | host_email_quota reports the per-second rate. |
| Paused | A paused address returns 403, and nothing is charged. |
| Transactional only | Use it for mail someone expects. Marketing belongs in Journeys. |
Errors
| Status | Meaning |
|---|---|
| 400 | Missing or invalid app_id, to, subject, body or from_local_part |
| 402 | The account that owns the Solution can't send (paid capability) |
| 404 | No such app or domain in your organization |
| 403 | Sending is paused for this app (see Sending health) |
| 409 | The address isn't verified yet. A ready-made one says it's still being set up. |
| 422 | Every recipient is suppressed (bounced or complained before); nothing sent or charged |
| 429 | Over today's sending limit |
| 503 | Sending addresses aren't available right now, or sending capacity is full (contact Waymaker) |