# Mail API reference

> Current emitted signatures and options for @db3.ai/app/mail.

- Package: `@db3.ai/app/mail`
- Canonical page: [https://db3.ai/docs/mail-api](https://db3.ai/docs/mail-api)
- Markdown: [https://db3.ai/docs/mail-api.md](https://db3.ai/docs/mail-api.md)
- Framework source of truth: `packages/app/src/mail/README.md`

<a id="start"></a>

## Imports and examples

Import supported APIs from `@db3.ai/app/mail`. These signatures come from the staged package used by consumers. Relative filenames in declarations describe type dependencies; they are not extra supported deep imports.

Use the guide for setup, executable examples, failure handling and ownership. A signature is not proof that every deployment or provider has been exercised.

- [Guide, examples and testing](https://db3.ai/docs/mail.md)

<a id="messages"></a>

## Message, delivery and custom transport contracts

### Message, delivery and custom transport contracts

```typescript
/** Recipient or sender as an address string or an email plus display name. */
export type MailAddress = string | {
    email: string;
    name?: string;
};
/** Application-owned message; templates and recipient authorization stay in the app. */
export interface MailMessage {
    to: MailAddress | MailAddress[];
    from?: MailAddress;
    subject: string;
    text?: string;
    html?: string;
    /** Extra message headers; File and Resend preserve them, Mailgun currently does not. */
    headers?: Record<string, string>;
}
/** Transport input with a default sender resolved and recipients normalized to an array. */
export interface ResolvedMailMessage extends Omit<MailMessage, 'from' | 'to'> {
    from: MailAddress;
    to: MailAddress[];
}
/** Provider acceptance or a local file write, not proof of inbox delivery. */
export interface MailDelivery {
    id: string;
    transport: string;
    accepted: string[];
    rejected: string[];
    /** Local JSON preview path when using the file transport. */
    path?: string;
}
/** Provider boundary; sending rejects on transport failure and never retries automatically. */
export interface MailTransport {
    /** Submits one normalized message to the selected transport. */
    send(message: ResolvedMailMessage): Promise<MailDelivery>;
}
/** Sender defaults and the explicitly selected transport for one Mail instance. */
export interface MailOptions {
    from?: MailAddress;
    transport?: MailTransport;
}
/** Application fallback sender, overridden by MAIL_FROM when present. */
export interface MailEnvOptions {
    from?: MailAddress;
}
/** Normalizes messages and delegates immediate delivery to one transport. */
export declare class Mail {
    private readonly from;
    private readonly transport;
    /** Creates a mail service; absent transport selects local file previews. */
    constructor(options?: MailOptions);
    /** Validates message presence and sends once; apps own retries and recipient policy. */
    send(message: MailMessage): Promise<MailDelivery>;
    /** Resolves the sender and recipient list without changing application content. */
    private resolveMessage;
}
/** Builds a shared Mail instance from an explicit environment or process.env. */
export declare function createMailFromEnv(env?: NodeJS.ProcessEnv, options?: MailEnvOptions): Mail;
/** Selects the transport; missing or unrecognized names currently fall back to file. */
export declare function createMailTransportFromEnv(env?: NodeJS.ProcessEnv): MailTransport;
/** Formats an address for transport use; this is not validation or header sanitization. */
export declare function formatMailAddress(address: MailAddress): string;
/** Extracts the address portion for acceptance metadata; does not validate deliverability. */
export declare function mailAddressEmail(address: MailAddress): string;
```

<a id="file"></a>

## File preview options

### File preview options

```typescript
import { type MailDelivery, type MailTransport, type ResolvedMailMessage } from '../Mail.js';
export interface FileMailTransportOptions {
    directory?: string;
}
/**
 * Development mail transport that writes each message to disk.
 */
export declare class FileMailTransport implements MailTransport {
    private readonly directory;
    constructor(options?: FileMailTransportOptions);
    send(message: ResolvedMailMessage): Promise<MailDelivery>;
}
```

<a id="resend"></a>

## Resend options

### Resend options

```typescript
import { type MailDelivery, type MailTransport, type ResolvedMailMessage } from '../Mail.js';
export interface ResendTransportOptions {
    apiKey: string;
    baseUrl?: string;
}
/**
 * Resend API transport.
 */
export declare class ResendTransport implements MailTransport {
    private readonly apiKey;
    private readonly baseUrl;
    constructor(options: ResendTransportOptions);
    send(message: ResolvedMailMessage): Promise<MailDelivery>;
}
```

<a id="mailgun"></a>

## Mailgun options and error

### Mailgun options and error

```typescript
import { type MailDelivery, type MailTransport, type ResolvedMailMessage } from '../Mail.js';
export interface MailgunTransportOptions {
    apiKey: string;
    domain: string;
    baseUrl?: string;
}
export declare class MailTransportError extends Error {
    constructor(message: string);
}
/**
 * Mailgun API transport.
 *
 * This keeps the app-level mail contract separate from the provider-specific
 * HTTP call, so production can swap providers without touching auth flows.
 */
export declare class MailgunTransport implements MailTransport {
    private readonly apiKey;
    private readonly domain;
    private readonly baseUrl;
    constructor(options: MailgunTransportOptions);
    send(message: ResolvedMailMessage): Promise<MailDelivery>;
}
```

## Related documentation
- [Mail](https://db3.ai/docs/mail.md): Build and preview an application email locally, then select a transport when you are ready to send it.

## Guidance for AI tools
Use the documented public import `@db3.ai/app/mail` and its exported types. Prefer the source-backed examples and behavioural outcomes above over invented APIs or source-relative internal imports.