Why does the platform broker send auth mail but not app mail? #
We host a contact backend on our own platform. Project posterior-contact, a small SvelteKit app with two server routes, one for contact mail and one for subscribe. We pointed it at our own email broker first, because that is what the docs suggest. It did not work, and the way it failed taught us where the edge sits.
The broker sends fixed auth templates. Verify email, password reset, magic link, one time code, recovery, welcome. Anything else returns 400. A contact form needs custom subject plus custom HTML to an internal address, and that shape has no path through the broker today. So auth mail still flows through the broker, and the contact route carries its own sender through Resend. Both live in the same project, each doing the job it fits.
What did the probes actually show? #
We probed more than twenty candidate types. App contact, app notification, app generic, app raw, notification, generic, transactional, mail, and the rest of the obvious guesses. Every one came back 400 Unknown email message type. The accepted set stayed fixed at six auth types, confirmed from the Better Auth integration response.
Then we checked whether valid sends would at least carry custom content. With a valid token, all six auth types returned 200 and delivered. But the delivered mail used the fixed template. A welcome send with custom subject plus probe HTML arrived with subject Welcome and none of the custom fields. Data is template shaped, custom body content does not render.
Try it: Domain Name Ideas — which helps name the project before you wire mail.
| Probe | Request shape | Response |
|---|---|---|
| Auth type with valid token | verify email plus standard data | 200, fixed template delivered |
| Auth type with custom body | welcome plus custom subject plus HTML | 200, custom fields ignored |
| App contact type | custom subject plus HTML to support address | 400 unknown type |
| App generic and raw guesses | twenty plus variants | 400 unknown type |
| Redacted token send | any type with placeholder value | 401 invalid token |
Why did the token path sting too? #
Setup returns the app env block with the token redacted as a literal placeholder, even with JSON output, even when piped. Persisting that output stores the placeholder, and every send then fails with 401. The tool to tool flow passes the raw value, so agents see it, but the CLI path has no supported way to read it into project env without a human copy step.
The workaround reads the raw tool text before display sanitizing and feeds it straight into env apply without printing. After reapplying, the token length moved from placeholder length to full length and broker accepts went green. That unblocked auth mail, but it did not change the type boundary above. Tokens were never the wall for contact mail. Types were.
How should you wire contact mail today? #
Keep the broker for what it does well and give app mail its own sender. Provision a Resend key plus verified sender subdomain as project owned env, accept them through the user supplied key path rather than the derived allowlist, and send from the server route directly. Add origin allowlisting on the route, verify bad origins get 403 and valid preflights get 204, and keep the broker keys in the project for auth flows.
| Choice | Use for | Avoid for |
|---|---|---|
| Platform broker | Auth templates with fixed shape | Custom subject plus HTML |
| Direct Resend | Contact forms and custom bodies | Bulk cold outreach |
| Project env request path | User supplied sender keys | Non secret app config |
| Server route proxy | Third party APIs with no client token scheme | Pure static embeds |
Who is this for? #
You run a static site or a small app and you need a contact form that reaches a human. You also use auth mail and you want one project to carry both. If your mail has custom subject plus custom body, plan for a direct sender from day one and keep the broker for auth.
One limit to know. The broker still accepts only fixed auth templates, so plan a direct sender for any custom subject plus body from day one. Setup output also redacts the token, so avoid persisting that placeholder or every send fails with 401.
- Best for developers wiring a contact form that needs custom subject and body content.
- Best for small business owners needing auth mail plus contact mail in one small app.
- Best for startups choosing between a built-in broker and a direct sender for app mail.
What are the trade-offs? #
The split inbox wins when each sender does what it proves. The platform broker sends fixed auth templates reliably, and a direct provider route through Resend with project owned keys carries contact bodies with custom subject plus HTML.
| Keep the broker when | Route through Resend when |
|---|---|
| The mail is auth shaped with a fixed template | The body, subject, or recipient varies per message |
| Zero provider setup matters more than customization | Deliverability, logs, and reply handling need control |
| Token delivery already returns 200 on valid sends | Probes return 400 Unknown email message type |
The broker loses the moment content varies: 20 plus probed types rejected, custom fields ignored even on 200s. Pick the alternative for app mail and keep the broker where it is proven.
What we learned building this? #
Dogfooding should hurt a little, or you are not testing the path users walk. We found the wall because we shipped a real form, not a demo. The fix we want is small and specific, a generic app send type that renders subject plus HTML plus text verbatim, or per project registration of custom types. Until that lands, the honest doc is the runbook above. We kept the feedback file in the repo with probe counts and error strings intact, so the next team does not repeat the dead ends. That file is the most useful artifact of the whole episode.