Email #

View this page as Markdown

Email lets an application's backend send an occasional request or notice, such as an order confirmation, a receipt, or an invitation, to up to five people at a time. Turn Zero Cloud sends each message from its own sending address under the application's name. Email send is a feature of the Pro plan.

The package provides your backend's side of that service. Its client sends one message under the application's platform credential. It reports what the send accepted, and it throws a typed refusal that gives the platform's refusal name and, when a count is reached, the time the application may send again.

Use it when #

Use Email when the backend must write to a person: a customer whose order shipped, a member invited to a team, a user who asked for a receipt. Declare the service by adding {"kind": "email"} to the manifest's services on a Pro application.

Do not use it for newsletters, marketing, or any mail to a long list. The plan counts each application's recipients by the hour, the day, and the month, and refuses a send past a count. For more volume, send through your own mail provider's API with your own key, as Call an external API with an API key describes.

What it provides #

• A client, createEmailClient, which The client describes. The module has no dependencies and keeps no state.
• A send. send(message) sends one message to the recipients it names.
• The response. Each send returns messageId and the recipients the platform accepted and counted. An address named twice counts once.
• A typed refusal. Every other response throws an EmailRefusal. Its refusal member is the platform's refusal name, members contains the refusal's other values, and resetsAt is the time a refused send may go again.
• A test double, createEmailDouble at @turnzero/email/testing, which answers a send as the platform does and records every send. Test with the double shows it in use.

A message carries no blind copy and no attachment. Its subject, text, and HTML hold 256 kilobytes at most together.

Availability #

Version 0.1.0 is the package's current version: this page describes it, and list_library returns the version the library serves now. The entry includes the testing subpath from version 0.1.0. The entry holds the compiled modules, the package's product statement and detailed contract, and its integration guide. Turn Zero Cloud runs the email service on the Pro plan, and read_usage returns the month's recipients under email_recipients, with the hour's and the day's counts beside it.

Related feature packages #

Logging records a refused send, and the application's log stream shows each message's outcome. Egress calls your own mail provider's API, for mail past the plan's counts.

The client #

The package is published in the library as the npm package @turnzero/email, not on the npm registry; Use the library installs it with one line that needs no account or sign-in.

createEmailClient(options) builds the client from one of two forms:

Give transport, or api and token, never both. At construction the client throws EmailClientError, code client_options, for both forms, a missing token, or an api that is not an http or https address. send(message, { signal }) returns a promise of { messageId, recipients }. A send the platform refuses rejects with EmailRefusal; Refusals lists its members and names.

Refusals #

Branch on the refusal's name, never on its message. An EmailRefusal has refusal, status, detail, members, and resetsAt. These are the refusals a send meets most often; the refusals page lists every refusal the platform answers, with its cause and remedy.

A send refused email_limit_reached queued nothing. Its members give the period, the count that stood, the plan's figure, and the send's own recipients. Its resetsAt is the first moment of the next hour, day, or month, in UTC, when the application may send again.

What an application must do #

Declare the service on a Pro application, and send from the backend under the platform credential, as Send email from your application describes.

Send once for each event. The client retries nothing, because a send the platform accepted before its response was lost is already queued, and a second send would mail the person twice.

Keep a refused send from failing the request that made it. Record the refusal, and respond to the request. After email_limit_reached, hold the message until resetsAt, or send it through your own provider.

Test with the double #

createEmailDouble(options) from @turnzero/email/testing answers a send as the platform does, from the plan's figures and the clock the test gives it. Build the client with createEmailClient({ transport: double.transport }), or pass double.fetch as the client's fetch. Read what was sent in double.sends. A test runs this sample over the double.

import assert from 'node:assert/strict';
import { createEmailClient, EmailRefusal } from '@turnzero/email';
import { createEmailDouble } from '@turnzero/email/testing';

// Two recipients an hour, and a clock fixed inside one hour.
const email = createEmailDouble({ cells: { hour: 2 }, now: () => new Date('2026-10-12T09:30:00Z') });
const client = createEmailClient({ transport: email.transport });

const sent = await client.send({ to: ['customer@example.com', 'customer@example.com'], cc: ['orders@example.com'], subject: 'Your order shipped', text: 'Your order is on its way.' });
assert.equal(sent.recipients, 2);
assert.equal(email.sends.length, 1);
// The hour's two recipients are spent, so the next send is refused by name, with the time it may go again.
await assert.rejects(
  client.send({ to: ['customer@example.com'], subject: 'Again', text: 'One more.' }),
  (error) => error instanceof EmailRefusal && error.refusal === 'email_limit_reached' && error.resetsAt.toISOString() === '2026-10-12T10:00:00.000Z',
);

The double refuses by the email route's own names, which Refusals lists. Its setup gives these: