DocsServer

Mail

Send email from hooks, agents, jobs and server functions, through one mail server set up in the admin UI.

Set up SMTP once, then send from any server code with mail(). Sign-in links, invitations, password resets and notifications all go through it. To send an email:

agents/receipts.ts
export async function act({ event, mail, link }) {
  const sent = await mail({
    to: event.data.email,
    subject: "Paid, thank you",
    text: `Your order is paid. See it at ${await link("/orders")}`,
  });
}

Features include:

  • One mail server for every app, set up in the admin
  • mail() in hooks, agents, jobs and server functions, which never throws
  • Links made absolute from the app’s base URL
  • Sign-in links, password resets and invitations in the app’s language

Set it up

In the admin, under Mail:

Host and portYour provider’s SMTP server: smtp.example.com, 587
Username, passwordThe password stays on the server and is never returned by the API
From, from nameThe sender’s address and the name shown, for example “Acme Shop”
Base URLWhere links in emails point. By default, the address the app is served at
TLSSTARTTLS; turn it off only for a local relay that doesn’t support it

Without a host, mail is off: nothing fails, and nothing is sent.

Send

  • mail({ to, subject, text }) resolves to true if the email was sent, and false if mail isn’t set up or the server refused it. Failures are logged, never thrown.
  • link(path) turns an app path into an absolute URL, using the base URL.

Mail is plain text on purpose. A notification points to something in the app and links to it; it isn’t the conversation itself, so nobody replies to an inbox no one reads.

Built-in emails

Sign-in links, password resets and invitations are sent in the app’s language. Conversation threads email the people who were offline when a message arrived; chat rooms never email, to keep inboxes quiet.

View as Markdown