Email

Toast selects an email driver from the validated config and loads it through getEmailDriver(...).

The important architectural rule: the loader receives config explicitly. It does not read process.env for itself.

Loader API

const driver = await getEmailDriver({
  driverName: config.drivers.emailDriver,
  isProduction: config.environment.nodeEnv === 'production',
  driverConfig: config.drivers.mailgun,
});

Selection logic

Driver name	Environment	Result
`null`	development	built-in console driver
`null`	production	throws — email driver required
`console`	any	built-in console driver
`toast-driver-email-mailgun`	any	Mailgun driver package

Console driver

The built-in console driver is used automatically in development when no email driver is configured.

It logs outgoing email to stdout and is useful for local auth flows and tests.

Mailgun driver

In the Toast repo, toast-driver-email-mailgun already exists as a workspace package under drivers/email-mailgun/ and is already referenced by apps/api.

If you are working outside this monorepo, install the package in the application that loads the driver.

The config layer passes Mailgun settings into the loader, which passes them into the driver constructor.

Relevant config values:

EMAIL_DRIVER=toast-driver-email-mailgun
MAILGUN_API_KEY
MAILGUN_DOMAIN
MAILGUN_REGION
EMAIL_FROM

Custom drivers

Custom driver classes should accept a config object in their constructor rather than reading env directly.

export default class ResendEmailDriver implements EmailDriver {
  constructor(private readonly config: { apiKey: string; from?: string }) {}

  async send(message: EmailMessage): Promise<SendResult> {
    // ...
    return { success: true, messageId: 'example' };
  }
}

See Driver overview for the generic pattern.

Troubleshooting

Driver missing in production — set EMAIL_DRIVER
Package not found — install the driver package in the workspace
Mailgun auth failures — verify API key, domain, and region values in config