Mail API reference

/** 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;

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>;
}

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>;
}

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>;
}