Email configuration

Set up email with exact runtime options, typed JavaScript/TypeScript examples and lifecycle policies.

Before you configure it#

Install the runtime and the packages used by this feature in the application directory. Keep the dependency lockfile committed. Configure only services the application actually uses; a public package name is not automatic service registration.

npm install zeruxjs @zeruxjs/email

JavaScript application setup#

/** @type {import('zeruxjs').ZeruxConfig} */
export default {
  email: {
  defaultAccount: 'transactional',
  maxRecipients: 20,
  accounts: [{ name: 'transactional', smtp: {
    host: process.env.SMTP_HOST,
    port: Number(process.env.SMTP_PORT || 587),
    secure: false,
    requireTLS: true,
    auth: { type: 'password', user: process.env.SMTP_USER, pass: process.env.SMTP_PASSWORD },
  }, defaults: { from: 'Application <noreply@example.com>' } }],
},
};

This example is a server configuration. Supply the referenced environment values through the server process before starting it. The documentation site's static exporter does not start this service merely because it imports a config file.

What each setting does#

Use named accounts and choose defaultAccount explicitly when there is more than one sender. SMTP credentials remain server-side. secure: false on port 587 normally means a connection upgraded through STARTTLS; requireTLS: true requires that upgrade. Port/transport settings must match the actual provider. SMTP acceptance is not final delivery.

Accounts may instead contain an application-supplied transport. Runtime bootstrap starts a sending manager only for accounts with SMTP/transport configuration. Inbound-only setup uses receive.accounts or account-level receive configuration. At least one sending or receiving account is required once the email service is configured.

Tracking, preferences, reputation, campaign dashboards and feedback are independent opt-in features. Tracking requires a public origin and signing secret/key ring. Preferences require a signing secret and a suitable persistent store in production. A signature verifier must validate provider feedback before the application accepts delivery or complaint events.

TypeScript configuration#

For a TypeScript application, use zerux.config.ts. Validate the service object separately so errors point to its option rather than a large application object. NonNullable removes the optional top-level absence; it does not invent defaults or validate external data at runtime.

import type { ZeruxConfig } from 'zeruxjs';

type Options = NonNullable<ZeruxConfig['email']>;
const options = {
  defaultAccount: 'transactional',
  maxRecipients: 20,
  accounts: [{ name: 'transactional', smtp: {
    host: process.env.SMTP_HOST,
    port: Number(process.env.SMTP_PORT || 587),
    secure: false,
    requireTLS: true,
    auth: { type: 'password', user: process.env.SMTP_USER, pass: process.env.SMTP_PASSWORD },
  }, defaults: { from: 'Application <noreply@example.com>' } }],
} satisfies Options;
export default { email: options } satisfies ZeruxConfig;

In JavaScript, the JSDoc annotation provides editor assistance. In TypeScript, satisfies checks the shape while preserving inferred literal values. Neither changes the runtime behavior or establishes a network connection during a typecheck. See TypeScript application development for strict settings and validation boundaries.

Lifecycle and failure policy#

Files initialize before email so stored attachments can be resolved. For persistent inbound mode, provide a named database connection or a host store. JSON inbound mode returns parsed messages without creating an inbox table; it is not a durable mailbox store. An inbox UI API still requires persistence and an authorization callback.

Separate transactional and marketing policies. Recheck consent and suppression at delivery time, use durable idempotency for retryable campaigns, and record ambiguous outcomes instead of blindly resending. Shutdown must release SMTP/receive resources. A queue job completion or SMTP response does not prove that an end user's mailbox accepted the message.

Verify a real integration#

1. Start the application with just this feature and its declared dependencies configured.
2. Check service readiness, then perform one operation through the application API.
3. Test a failure path such as unavailable infrastructure or a rejected input.
4. Restart the runtime and verify that owned resources close and state behaves according to the chosen storage model.
5. Repeat with the production build and the real deployment identity; a successful static docs build does not test external services.

Declared options#

The following table is captured from the source contract used by runtime bootstrap. Optional means a property may be omitted; it does not mean every combination is meaningful. Callback and nested adapter shapes must satisfy the full declared type.

Continue with the package#

• email
• durable email
• files
• queue