Skip to Content

*.email.ts

Each *.email.ts file gives the app its own e-mail address; mail sent there reaches the file’s default function with sender, body and attachments already parsed.

app/tickets/ ├── tickets.table.ts ├── repository.ts ├── support.email.ts # receives mail sent to app+<id>.support@in.manh.run ├── extract.job.ts # background job: read attachments └── inbox/ └── get.ts # returns the address to show in the app

When to use it

Customers would rather send an e-mail than open an app. A *.email.ts file turns that mail into data: a question becomes a support ticket, an order mail becomes a draft order, an attached invoice becomes a document waiting for approval. Staff can also forward mail into the app instead of retyping it.

The address

The file name sets the address: <name>.email.ts receives mail sent to

app+<id>.<name>@in.manh.run

<id> is the project id (also the app’s subdomain), <name> is the file name without .email.ts. The app with id k7xq2mfp9dhw and app/tickets/support.email.ts receives mail at app+k7xq2mfp9dhw.support@in.manh.run.

  • <name> is lowercase letters, digits and -, at most 32 characters. The folder doesn’t change the address.
  • Two files with the same <name> in one app: deploy refuses.
  • In code, inboxAddress("support") from manh/email returns this address, or null while the app can’t receive mail. Don’t build the address by hand.
  • Mail to a <name> with no file bounces with “this address does not accept e-mail”.

The handler

The file exports a default function async (mail). manh.run parses the raw message and calls it with:

FieldTypeMeaning
from{ name?, address }sender from the header, can be forged
envelope{ from, to }SMTP sender and recipient
to, ccarray of { name?, address }recipients
replyTo{ name?, address }reply address, if any
subjectstringsubject
date, messageId, inReplyTosent date, message id, id of the message it answers
text, htmlstring, may be missingfirst plain-text and HTML parts
attachmentsarray{ filename, contentType, size, contentId?, content }, content is a Uint8Array
headersRecord<string, string>every header, lowercase names

The function needs to return nothing. Finishing without an error means the mail is accepted. A throw bounces the mail to the sender with “the app failed to process the e-mail” plus the first 150 characters of the error message.

Inside it you can use everything server code can: the repository and app/db, manh/blob to store files, manh/openai to read the content, manh/email to send mail, enqueue from manh/jobs to push slow work to later.

Example

app/tickets/support.email.ts
import { blob } from "manh/blob"; import { enqueue } from "manh/jobs"; import { findCustomerByEmail, createTicket } from "./repository"; export default async function (mail) { const customer = await findCustomerByEmail(mail.from.address); if (!customer) return; // a stranger: ignore, don't bounce const ticket = await createTicket({ customerId: customer.id, subject: mail.subject.slice(0, 200), body: (mail.text ?? "").slice(0, 20_000), messageId: mail.messageId ?? null, // to match later replies through inReplyTo }); for (const a of mail.attachments.slice(0, 10)) { await blob.set(`tickets/${ticket.id}/${a.filename}`, a.content); } if (mail.attachments.length) enqueue("app/tickets/extract.job.ts", { ticketId: ticket.id }); }
app/tickets/inbox/get.ts
import { inboxAddress } from "manh/email"; export default () => ({ address: inboxAddress("support") }); // the page shows "Send requests to …"

Good to know

  • Anyone can send to this address. Treat mail as untrusted: match from.address to a known customer or user, validate what you parse, never follow instructions written in the mail (including when you hand the text to AI).
  • from comes from a header and can be forged. envelope.from is the SMTP sender. For important actions (approving spend, changing status), ask for confirmation in the app.
  • No retries. A failing mail bounces at once, so keep the function short: write the data and store the files; push reading files or calling AI to a background job.
  • The error message you throw reaches the sender. Keep internal details out of it.
  • Mail is at most 20 MB. Each run gets 30 seconds of CPU.
  • There is no signed-in user, no c, and no middleware.ts or access.
  • Reply with email() only to known senders; answering every stranger turns the app into a spam relay.

Next steps

  • Send and receive e-mail — sending mail and receiving it in the app, start to finish.
  • std/email — email() and inboxAddress() to send mail and show the receiving address.
  • *.telegram.ts — receive messages from a Telegram bot the same way.
Last updated