Skip to Content

email

Send email from your app’s server code with manh/email, no API key needed.

Usage

app/bookings/repository.ts
import { email, html, raw, mailFrame } from "manh/email"; export async function confirmBooking(b: Booking, customer: Customer) { // … write to the database first const body = html`<p>Hi ${customer.name},</p><p>Your appointment is confirmed.</p>`; await email({ to: customer.email, subject: "Appointment confirmed", html: mailFrame(body, { title: "Appointment", footer: raw("Hotline 1900 1234") }), safe: true, // a failed send doesn't break the booking }); }

Use it in .ts files only. Send mail after the database write.

Signature

manh/email
function email(o: { to: string | string[]; subject: string; html?: string; text?: string; cc?: string | string[]; bcc?: string | string[]; replyTo?: string; fromName?: string; safe?: boolean; }): Promise<{ ok: boolean; id?: string | null; skipped?: boolean; test?: boolean; error?: string }>; function html(strings: TemplateStringsArray, ...values: unknown[]): Html; function raw(s: string): Html; function mailFrame(body: Html | string, o?: { title?: string; footer?: Html | string; color?: string; appName?: string }): Html; function inboxAddress(name: string): string | null;

Parameters

email(o):

  • to: the recipients, required. At most 10 addresses across to, cc and bcc.
  • subject: the subject line.
  • html or text: the content; at least one is needed.
  • cc, bcc: extra recipients.
  • replyTo: the address that receives replies.
  • fromName: the sender name shown, the project name by default, up to 64 characters. The sending address is always no-reply@manh.run.
  • safe: true means it never throws.

html is a tagged template: every ${…} value is escaped. Nest another html or raw(…) for markup you trust. mailFrame(body, o) wraps the content into a complete, phone-friendly email with the app name on top.

Returns

email returns a Promise of an object with ok:

  • Sent: { ok: true, id }.
  • A made-up address with no mailbox (ending in .invalid, .example, .test, or example.com): nothing is sent, it returns { ok: false, skipped: true, error }.
  • A role test account (…@test.manh.invalid): the mail never leaves, it only lands in the logs, and it returns { ok: true, test: true }.
  • Any other failure: the promise rejects; with safe: true it resolves { ok: false, error }.

Check ok before telling the user “sent”. Relative links in the mail (/khach-hang/12) become full links on the app’s domain. Every send writes a line to the app’s logs ([email] sent to … or [email] FAILED to …), so the logs double as the outbox. Mail to a test account also logs the start of the body (plain text, links with their address) for outbox tests to check.

inboxAddress(name) returns the address that delivers to the name.email.ts file, or null when the app can’t receive mail yet.

Examples

Receiving mail doesn’t use email(). Mail sent to the app’s address goes to a *.email.ts file, see Receive email: *.email.ts. Get the address to show it to users:

app/tickets/inbox/get.ts
import { inboxAddress } from "manh/email"; export default () => ({ address: inboxAddress("support") }); // delivers to support.email.ts
  • The sending quota depends on the plan, counts recipients and is shared by every app of the account. Over it, calls fail with 429 BUILTIN_QUOTA_EXCEEDED; the app keeps running. Don’t retry a 429 in a loop.
  • To mail many people, send one message per recipient from a background job instead of a loop inside the request.
  • On the Free plan, ” via manh.run” is appended to the sender name.

Next steps

Last updated