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’screatedBycan be named in an API request, itsownerIdcannot.externalRecipient: the address is not a member of the organization (isOrganizationMemberEmail).
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.
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.