Waymaker
WaymakerDocs
Developer Documentation
Documentation

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 the volume they're measured over;
  • limits: the rates that pause sending automatically;
  • sending_enabled, paused_at and paused_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.

CommandWhat 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> --confirmStops 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

LimitWhat happens
Daily rampA 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.
Ratehost_email_quota reports the per-second rate.
PausedA paused address returns 403, and nothing is charged.
Transactional onlyUse it for mail someone expects. Marketing belongs in Journeys.

Errors

StatusMeaning
400Missing or invalid app_id, to, subject, body or from_local_part
402The account that owns the Solution can't send (paid capability)
404No such app or domain in your organization
403Sending is paused for this app (see Sending health)
409The address isn't verified yet. A ready-made one says it's still being set up.
422Every recipient is suppressed (bounced or complained before); nothing sent or charged
429Over today's sending limit
503Sending addresses aren't available right now, or sending capacity is full (contact Waymaker)