Skip to main content
Every email the application sends goes through one function, sendEmail in apps/web/modules/email/lib/send-email.ts. Each call names an email type (TEmailType), which tags the message in SES metrics and decides which limits apply, and goes to exactly one address: sendEmail refuses a list. Emails sent by other systems (Stripe, identity providers, marketing tools) are not covered here.

How email is limited

emailRateLimits (modules/email/lib/email-rate-limits.ts) gives every type its limits, and sendEmail charges them before it opens an SMTP connection. The caller says who the email is sent for in rateLimit:
  • organizationId: the organization it is sent for.
  • actorUserId: the signed-in user who acted, or the owner of the survey or workflow that sent it (resolveEmailActorUserId, which charges the organization’s owner when one was created with an API key). It is counted across all of their organizations, so a fresh organization does not reset it. That reset is how INC-5 sent about 13,000 invites through throwaway organizations. Take it only from a field the server sets: a survey’s createdBy can be named in an API request, its ownerId cannot.
  • externalRecipient: the address is not a member of the organization (isOrganizationMemberEmail).
A type’s limits can count per organization, per actor, per recipient and per deployment, and types can share one budget. All of them are charged together, and a refused email hands the others back. A refusal throws TooManyRequestsError. The values, and what each flow does with a refusal, are listed in Rate Limiting. Three rules shape those limits:
  • Whoever can trigger an email must not be able to stop it for anyone else. A per-deployment cap is shared by every tenant, so only email a signed-in user sends to an address they typed in has one. Respondents and visitors trigger follow-ups, workflow emails and verified links, so those have none. A follow-up or workflow email to an address the author typed that belongs to a member is not counted at all.
  • A per-recipient cap must not let one sender block someone. It counts one address from one organization. Only account email, which an address gets from its own account alone, is counted across everyone. Where a stranger can ask for account email (forgot password, a verification resend), the per-account limit where it starts sits below the recipient cap, so strangers cannot spend all of it.
  • Spreading email across types gains nothing. Follow-ups, workflow emails and verified links to outside addresses share one budget per organization and per owner. The owner’s cap is the higher of the two, so respondents flooding one organization stop at its cap and cannot use up the owner’s email elsewhere.
Some flows also limit where they start, before any email exists: invites count recipients per organization and per inviting user, and forgot-password counts per IP and per account.

Inventory

“Who picks the recipient” is the question that matters most. An address a user or visitor typed in can be anyone’s.

Checklist for a new email feature

1

Add an email type and its limits

Add the type to TEmailType and an entry to emailRateLimits; the Record type does not compile without one. Limit the organization and the actor. Add a recipient cap if someone other than the server picks the address. Add a per-deployment cap only if a signed-in user is the only one who can trigger the email.
2

Pass who the email is sent for

Set rateLimit on the sendEmail call. For email a visitor triggers, the actor is the owner of the survey or workflow (resolveEmailActorUserId), so they cannot use visitors to reach any address. Use only values the server set. sendEmail throws if a field the type needs is missing.
3

Test it with fresh resources

Show that the actor’s limit still holds after they create a new organization, survey or workflow.
4

Send what the server knows, not what the client sent

Read names and other display values from the database. Bound free text that appears in the email, and do not let identity fields (names, survey names) carry links. toEmailDisplayText does both, for invite names and the verify-email survey name alike.
5

Handle a refused send

In an interactive action, let TooManyRequestsError reach the user, unless the response must look the same whether or not an account or address exists. If the email follows a record you already saved, treat it as best-effort. In a background job, do not record the email as delivered.
6

Keep the address out of logs

Log the email type and ids, never the recipient address.
7

Update this page and the rate-limit docs

Add the type to the inventory above and to Rate Limiting.