@visulima/email 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/index.d.ts

@@ -1,9 +1,785 @@
-export { type AttachmentDataOptions, type AttachmentOptions, detectMimeType, generateContentId, readFileAsBuffer } from "./attachment-helpers.d.ts";
-export { default as EmailError } from "./errors/email-error.d.ts";
-export { default as RequiredOptionError } from "./errors/required-option-error.d.ts";
-export { createMail, Mail, type MailGlobalConfig, type SendableMessage } from "./mail.d.ts";
-export { default as MailMessage } from "./mail-message.d.ts";
-export type { Provider, ProviderFactory } from "./providers/provider.d.ts";
-export { defineProvider } from "./providers/provider.d.ts";
-export type { TemplateRenderer } from "./template-engines/types.d.ts";
-export type { Attachment, BaseConfig, CalendarEventOptions, EmailAddress, EmailHeaders, EmailOptions, EmailResult, EmailTag, FeatureFlags, ImmutableHeaders, MaybePromise, Priority, Receipt, Result, } from "./types.d.ts";
+import { Buffer as Buffer$1 } from 'node:buffer';
+import { ICalCalendar } from 'ical-generator';
+import { b as EmailAddress, e as EmailHeaders, P as Priority, C as CalendarEventOptions, E as EmailOptions, A as Attachment, a as EmailResult, R as Result, d as Receipt } from "./packem_shared/types.d-wwpgA3to.js";
+export { type B as BaseConfig, type c as EmailTag, type F as FeatureFlags, type I as ImmutableHeaders, type M as MaybePromise } from "./packem_shared/types.d-wwpgA3to.js";
+import { E as EmailSigner, a as EmailEncrypter } from "./packem_shared/types.d-CNnnk-Ya.js";
+import { T as TemplateRenderer } from "./packem_shared/types.d-nyR1ty1Q.js";
+import { a as Provider } from "./packem_shared/provider.d-DcfYeGJJ.js";
+export { type P as ProviderFactory, d as defineProvider } from "./packem_shared/provider.d-DcfYeGJJ.js";
+/**
+* Detects MIME type from filename using mime package.
+* Falls back to application/octet-stream if not found.
+* @param filename The filename or path.
+* @returns MIME type or application/octet-stream as fallback.
+*/
+declare const detectMimeType: (filename: string) => string;
+/**
+* Generates a Content-ID for inline attachments.
+* @param filename The filename to generate CID from.
+* @returns A unique Content-ID string.
+*/
+declare const generateContentId: (filename: string) => string;
+/**
+* Reads file and returns its content as Buffer.
+* @param filePath Path to the file.
+* @returns Buffer containing file content.
+*/
+declare const readFileAsBuffer: (filePath: string) => Promise<Buffer$1>;
+/**
+* Attachment options for helper methods
+*/
+interface AttachmentOptions {
+  /**
+  * Content-ID for inline attachments (used in HTML with cid:).
+  * If not provided and contentDisposition is 'inline', will be auto-generated.
+  */
+  cid?: string;
+  /**
+  * Content disposition type.
+  * 'attachment' (default) or 'inline'.
+  */
+  contentDisposition?: "attachment" | "inline";
+  /**
+  * MIME type of the attachment.
+  * If not provided, will be detected from filename.
+  */
+  contentType?: string;
+  /**
+  * Content transfer encoding.
+  * Examples: 'base64', '7bit', 'quoted-printable'.
+  */
+  encoding?: string;
+  /**
+  * Custom filename.
+  * Used when different from the file path.
+  */
+  filename?: string;
+  /**
+  * Custom headers for this attachment.
+  */
+  headers?: Record<string, string>;
+}
+/**
+* Attachment data options (for raw data attachments)
+*/
+interface AttachmentDataOptions extends AttachmentOptions {
+  /**
+  * Filename for the attachment.
+  * Required for raw data attachments.
+  */
+  filename: string;
+}
+interface ErrorProperties {
+  cause?: unknown;
+  hint?: ErrorHint;
+  location?: ErrorLocation;
+  message?: string;
+  name: string;
+  stack?: string;
+  title?: string;
+}
+interface ErrorLocation {
+  column?: number;
+  file?: string;
+  line?: number;
+}
+/**
+* A message that explains to the user how they can fix the error.
+* @example
+* ```ts
+* const error = new VisulimaError({
+*    hint: "Try running `npm install` to install missing dependencies.",
+*    location: {
+*    file: "src/index.ts",
+*    line: 1,
+*    column: 1,
+*    },
+*    message: "Cannot find module 'react'",
+*    name: "ModuleNotFoundError",
+* });
+* ```
+*
+* For more complex hints, you can pass an array of strings or a single string in markdown format.
+*/
+type ErrorHint = string[] | string;
+declare class VisulimaError extends Error {
+  loc: ErrorLocation | undefined;
+  title: string | undefined;
+  /**
+  * A message that explains to the user how they can fix the error.
+  */
+  hint: ErrorHint | undefined;
+  type: string;
+  constructor({
+    cause,
+    hint,
+    location,
+    message,
+    name,
+    stack,
+    title
+  }: ErrorProperties);
+  setLocation(location: ErrorLocation): void;
+  setName(name: string): void;
+  setMessage(message: string): void;
+  setHint(hint: ErrorHint): void;
+}
+/**
+* Will return an array of all causes in the error in the order they occurred.
+*/
+/**
+* Base error class for email package operations.
+* @param component The component name where the error occurred.
+* @param message The error message describing what went wrong.
+* @param options Optional error options including cause, code, and hint.
+*/
+declare class EmailError extends VisulimaError {
+  readonly component: string;
+  readonly code?: string;
+  constructor(component: string, message: string, options?: {
+    cause?: Error | unknown;
+    code?: string;
+    hint?: string | string[];
+  });
+}
+/**
+* Error for missing required options
+* @param component The component name where the error occurred
+* @param name The name(s) of the missing required option(s)
+*/
+declare class RequiredOptionError extends EmailError {
+  constructor(component: string, name: string | string[]);
+}
+type AddressInput = EmailAddress | EmailAddress[] | string | string[];
+/**
+* Mail message builder - provides fluent interface for building emails.
+*/
+declare class MailMessage {
+  private fromAddress?;
+  private toAddresses;
+  private ccAddresses;
+  private bccAddresses;
+  private subjectText;
+  private textContent?;
+  private textCharset;
+  private autoTextEnabled;
+  private htmlContent?;
+  private htmlCharset;
+  private dateValue?;
+  private returnPathAddress?;
+  private senderAddress?;
+  private headers;
+  private attachments;
+  private replyToAddress?;
+  private priorityValue?;
+  private tagsValue;
+  private signer?;
+  private encrypter?;
+  private logger?;
+  private icalEventData?;
+  /**
+  * Sets the sender address.
+  * @param address The sender email address (string or EmailAddress object).
+  * @returns This instance for method chaining.
+  */
+  from(address: EmailAddress | string): this;
+  /**
+  * Sets the recipient address(es).
+  * @param address The recipient email address(es) (string, EmailAddress, or arrays of either).
+  * @returns This instance for method chaining.
+  */
+  to(address: AddressInput): this;
+  /**
+  * Sets the CC recipient address(es).
+  * @param address The CC recipient email address(es) (string, EmailAddress, or arrays of either).
+  * @returns This instance for method chaining.
+  */
+  cc(address: AddressInput): this;
+  /**
+  * Sets the BCC recipient address(es).
+  * @param address The BCC recipient email address(es) (string, EmailAddress, or arrays of either).
+  * @returns This instance for method chaining.
+  */
+  bcc(address: AddressInput): this;
+  /**
+  * Sets the subject line for the email message.
+  * @param text The subject text to set.
+  * @returns This instance for method chaining.
+  */
+  subject(text: string): this;
+  /**
+  * Sets the plain text content of the email.
+  * @param content The plain text content to set.
+  * @param charset Optional charset for the text content (default: 'utf8').
+  * @returns This instance for method chaining.
+  */
+  text(content: string, charset?: string): this;
+  /**
+  * Sets the HTML content of the email.
+  * @param content The HTML content to set.
+  * @param charset Optional charset for the HTML content (default: 'utf8').
+  * @returns This instance for method chaining.
+  */
+  html(content: string, charset?: string): this;
+  /**
+  * Sets a custom email header.
+  * @param name The header name to set.
+  * @param value The header value to set.
+  * @returns This instance for method chaining.
+  */
+  header(name: string, value: string): this;
+  /**
+  * Sets multiple headers.
+  * Accepts both Record&lt;string, string> and ImmutableHeaders.
+  * @param headers The headers to set (Record or ImmutableHeaders).
+  * @returns This instance for method chaining.
+  */
+  setHeaders(headers: EmailHeaders): this;
+  /**
+  * Attaches a file from path (reads file from filesystem).
+  * Similar to Laravel's attach() method.
+  * @param filePath The absolute or relative filesystem path to the file to attach.
+  * @param options Optional attachment configuration (filename, contentType, etc.).
+  * @returns This instance for method chaining.
+  * @example
+  * ```ts
+  * message.attachFromPath('/path/to/file.pdf')
+  * message.attachFromPath('/path/to/file.pdf', { filename: 'custom-name.pdf' })
+  * ```
+  */
+  attachFromPath(filePath: string, options?: AttachmentOptions): Promise<this>;
+  /**
+  * Attaches raw data (string or Buffer).
+  * Similar to Laravel's attachData() method.
+  * @param content The content to attach (string or Buffer).
+  * @param options Attachment options including filename.
+  * @returns This instance for method chaining.
+  * @example
+  * ```ts
+  * message.attachData(Buffer.from('content'), 'file.txt')
+  * message.attachData('content', 'file.txt', { contentType: 'text/plain' })
+  * ```
+  */
+  attachData(content: string | Buffer, options: AttachmentDataOptions): this;
+  /**
+  * Embeds an inline attachment from file path (for images in HTML).
+  * Similar to Laravel's embed() method.
+  * Returns the Content-ID that can be used in HTML: &lt;img src="cid:{cid}">.
+  * @param filePath The path to the file to embed.
+  * @param options Optional attachment options (filename, contentType, etc.).
+  * @returns The Content-ID string that can be used in HTML.
+  * @example
+  * ```ts
+  * const cid = await message.embedFromPath('/path/to/logo.png')
+  * message.html(`<img src="cid:${cid}">`)
+  * ```
+  */
+  embedFromPath(filePath: string, options?: Omit<AttachmentOptions, "contentDisposition" | "cid">): Promise<string>;
+  /**
+  * Embeds raw data as inline attachment (for images in HTML).
+  * Similar to Laravel's embedData() method.
+  * Returns the Content-ID that can be used in HTML: &lt;img src="cid:{cid}">.
+  * @param content The content to embed (string or Buffer).
+  * @param filename The filename for the embedded attachment.
+  * @param options Optional attachment options (contentType, etc.).
+  * @returns The Content-ID string that can be used in HTML.
+  * @example
+  * ```ts
+  * const imageBuffer = Buffer.from('...')
+  * const cid = message.embedData(imageBuffer, 'logo.png', { contentType: 'image/png' })
+  * message.html(`<img src="cid:${cid}">`)
+  * ```
+  */
+  embedData(content: string | Buffer, filename: string, options?: Omit<AttachmentDataOptions, "filename" | "contentDisposition" | "cid">): string;
+  /**
+  * Sets the reply-to address.
+  * @param address The reply-to email address (string or EmailAddress object).
+  * @returns This instance for method chaining.
+  */
+  replyTo(address: EmailAddress | string): this;
+  /**
+  * Sets the date header for the email.
+  * @param date The date to set (Date object or ISO string).
+  * @returns This instance for method chaining.
+  */
+  date(date: Date | string): this;
+  /**
+  * Sets the return-path address (bounce address).
+  * @param address The return-path email address (string or EmailAddress object).
+  * @returns This instance for method chaining.
+  */
+  returnPath(address: EmailAddress | string): this;
+  /**
+  * Sets the sender address (different from From - used when From contains multiple addresses).
+  * @param address The sender email address (string or EmailAddress object).
+  * @returns This instance for method chaining.
+  */
+  sender(address: EmailAddress | string): this;
+  /**
+  * Adds recipient address(es) without replacing existing ones.
+  * @param address The recipient email address(es) (string, EmailAddress, or arrays of either).
+  * @returns This instance for method chaining.
+  */
+  addTo(address: AddressInput): this;
+  /**
+  * Adds CC recipient address(es) without replacing existing ones.
+  * @param address The CC recipient email address(es) (string, EmailAddress, or arrays of either).
+  * @returns This instance for method chaining.
+  */
+  addCc(address: AddressInput): this;
+  /**
+  * Adds BCC recipient address(es) without replacing existing ones.
+  * @param address The BCC recipient email address(es) (string, EmailAddress, or arrays of either).
+  * @returns This instance for method chaining.
+  */
+  addBcc(address: AddressInput): this;
+  /**
+  * Adds reply-to address(es) without replacing existing ones.
+  * @param address The reply-to email address(es) (string, EmailAddress, or arrays of either).
+  * @returns This instance for method chaining.
+  */
+  addReplyTo(address: EmailAddress | string | (EmailAddress | string)[]): this;
+  /**
+  * Adds from address(es) without replacing existing ones.
+  * @param address The sender email address(es) (string, EmailAddress, or arrays of either).
+  * @returns This instance for method chaining.
+  */
+  addFrom(address: EmailAddress | string | (EmailAddress | string)[]): this;
+  /**
+  * Sets the email priority.
+  * @param priority The priority level ('high', 'normal', or 'low').
+  * @returns This instance for method chaining.
+  */
+  priority(priority: Priority): this;
+  /**
+  * Sets email tags for categorization.
+  * @param tags The tags to set (string or array of strings).
+  * @returns This instance for method chaining.
+  */
+  tags(tags: string | string[]): this;
+  /**
+  * Signs the email message using a signer (DKIM or S/MIME).
+  * @param signer The signer instance to use.
+  * @example
+  * ```ts
+  * import { createDkimSigner } from '@visulima/email/crypto';
+  * const signer = createDkimSigner({
+  *   domainName: 'example.com',
+  *   keySelector: 'default',
+  *   privateKey: '-----BEGIN PRIVATE KEY-----...'
+  * });
+  * message.sign(signer)
+  * ```
+  */
+  sign(signer: EmailSigner): this;
+  /**
+  * Encrypts the email message using an encrypter (S/MIME).
+  * @param encrypter The encrypter instance to use.
+  * @example
+  * ```ts
+  * import { createSmimeEncrypter } from '@visulima/email/crypto';
+  * const encrypter = createSmimeEncrypter({
+  *   certificates: '/path/to/certificate.crt'
+  * });
+  * message.encrypt(encrypter)
+  * ```
+  */
+  encrypt(encrypter: EmailEncrypter): this;
+  /**
+  * Sets the logger instance for this message.
+  * @param logger The logger instance (Console) to use for logging.
+  * @returns This instance for method chaining.
+  * @example
+  * ```ts
+  * message.logger(console)
+  * ```
+  */
+  setLogger(logger: Console): this;
+  /**
+  * Attach a calendar event and define contents as string or function.
+  * @param contents The calendar content as a string or a function that receives an ICalCalendar instance.
+  * @param options Optional calendar event options (method, alternativeText).
+  * @returns This instance for method chaining.
+  * @example
+  * ```ts
+  * message.icalEvent((calendar) => {
+  *   calendar.createEvent({
+  *     start: new Date(),
+  *     summary: 'Meeting'
+  *   });
+  * })
+  * message.icalEvent('BEGIN:VCALENDAR...')
+  * ```
+  */
+  icalEvent(contents: ((calendar: ICalCalendar) => void) | string, options?: CalendarEventOptions): this;
+  /**
+  * Attach a calendar event and load contents from a file.
+  * @param file The file path (string or URL) to load the calendar event from.
+  * @param options Optional calendar event options (method, alternativeText).
+  * @returns This instance for method chaining.
+  * @example
+  * ```ts
+  * message.icalEventFromFile('/path/to/event.ics')
+  * message.icalEventFromFile(new URL('file:///path/to/event.ics'))
+  * ```
+  */
+  icalEventFromFile(file: string | URL, options?: CalendarEventOptions): this;
+  /**
+  * Attach a calendar event and load contents from a URL.
+  * @param url The URL to fetch the calendar event from.
+  * @param options Optional calendar event options (method, alternativeText).
+  * @returns This instance for method chaining.
+  * @example
+  * ```ts
+  * message.icalEventFromUrl('https://example.com/event.ics')
+  * ```
+  */
+  icalEventFromUrl(url: string, options?: CalendarEventOptions): this;
+  /**
+  * Renders a template and sets as HTML content.
+  * Accepts a render function for flexible template engine support.
+  * @param render The template renderer function.
+  * @param template The template content (string, React component, etc.).
+  * @param data Optional data/variables to pass to the template.
+  * @param options Optional renderer-specific options.
+  * @param options.autoText Whether to auto-generate text version from HTML (default: true).
+  * @returns This instance for method chaining.
+  * @example
+  * ```ts
+  * import { renderHandlebars } from '@visulima/email/template/handlebars';
+  * message.view(renderHandlebars, '<h1>Hello {{name}}!</h1>', { name: 'John' })
+  *
+  * import { renderMjml } from '@visulima/email/template/mjml';
+  * message.view(renderMjml, mjmlTemplate)
+  *
+  * import { renderReactEmail } from '@visulima/email/template/react-email';
+  * message.view(renderReactEmail, <WelcomeEmail name="John" />)
+  * ```
+  */
+  view(render: TemplateRenderer, template: unknown, data?: Record<string, unknown>, options?: {
+    [key: string]: unknown;
+    autoText?: boolean;
+  }): Promise<this>;
+  /**
+  * Renders a text template and sets as text content.
+  * @param render The template renderer function.
+  * @param template The text template content.
+  * @param data Optional data/variables to pass to the template.
+  * @param options Optional renderer-specific options.
+  * @returns This instance for method chaining.
+  * @example
+  * ```ts
+  * import { renderHandlebars } from '@visulima/email/template/handlebars';
+  * message.viewText(renderHandlebars, 'Hello {{name}}!', { name: 'John' })
+  * ```
+  */
+  viewText(render: TemplateRenderer, template: string, data?: Record<string, unknown>, options?: Record<string, unknown>): Promise<this>;
+  /**
+  * Builds the email options.
+  * @returns The built email options ready for sending.
+  * @throws {Error} When required fields (from, to, subject, content) are missing.
+  */
+  build(): Promise<EmailOptions>;
+  /**
+  * Gets the subject of the email.
+  * @returns The subject text or empty string if not set.
+  */
+  getSubject(): string;
+  /**
+  * Gets the from address.
+  * @returns The from address or undefined if not set.
+  */
+  getFrom(): EmailAddress | undefined;
+  /**
+  * Gets the recipient addresses.
+  * @returns Array of recipient addresses.
+  */
+  getTo(): EmailAddress[];
+  /**
+  * Gets the CC recipient addresses.
+  * @returns Array of CC recipient addresses.
+  */
+  getCc(): EmailAddress[];
+  /**
+  * Gets the BCC recipient addresses.
+  * @returns Array of BCC recipient addresses.
+  */
+  getBcc(): EmailAddress[];
+  /**
+  * Gets the reply-to address.
+  * @returns The reply-to address or undefined if not set.
+  */
+  getReplyTo(): EmailAddress | undefined;
+  /**
+  * Gets the sender address.
+  * @returns The sender address or undefined if not set.
+  */
+  getSender(): EmailAddress | undefined;
+  /**
+  * Gets the return-path address.
+  * @returns The return-path address or undefined if not set.
+  */
+  getReturnPath(): EmailAddress | undefined;
+  /**
+  * Gets the date header.
+  * @returns The date or undefined if not set.
+  */
+  getDate(): Date | undefined;
+  /**
+  * Gets the priority of the email.
+  * @returns The priority ('high', 'normal', 'low') or undefined if not set.
+  */
+  getPriority(): Priority | undefined;
+  /**
+  * Gets the plain text content.
+  * @returns The text content or undefined if not set.
+  */
+  getTextBody(): string | undefined;
+  /**
+  * Gets the charset for the text content.
+  * @returns The text charset (default: 'utf8').
+  */
+  getTextCharset(): string;
+  /**
+  * Gets the HTML content.
+  * @returns The HTML content or undefined if not set.
+  */
+  getHtmlBody(): string | undefined;
+  /**
+  * Gets the charset for the HTML content.
+  * @returns The HTML charset (default: 'utf8').
+  */
+  getHtmlCharset(): string;
+  /**
+  * Gets the attachments.
+  * @returns Array of attachments.
+  */
+  getAttachments(): Attachment[];
+  /**
+  * Attempts to auto-generate text content from HTML.
+  * @param html The HTML content to convert.
+  * @private
+  */
+  private tryAutoGenerateText;
+  /**
+  * Creates an error, logs it, and throws it.
+  * @param message Error message to throw.
+  * @param logMessage Optional log message (defaults to message).
+  * @private
+  */
+  private throwAndLogError;
+}
+/**
+* Draft mail message - extends MailMessage with X-Unsent header automatically set.
+* Draft messages cannot be sent directly - they must be converted to regular messages first.
+*/
+declare class DraftMailMessage extends MailMessage {
+  /**
+  * Creates a new draft mail message.
+  * The X-Unsent header is automatically set to '1' to mark this as a draft.
+  */
+  constructor();
+}
+/**
+* Type alias for messages that can be sent via Mail.send().
+*/
+type SendableMessage = MailMessage | EmailOptions;
+/**
+* Global email configuration that applies to all emails sent through a Mail instance.
+*/
+interface MailGlobalConfig {
+  /**
+  * Default from address to use if not specified in the message.
+  */
+  from?: EmailAddress;
+  /**
+  * Global headers to add to all emails.
+  * These will be merged with message-specific headers, with message headers taking precedence.
+  */
+  headers?: EmailHeaders;
+  /**
+  * Default reply-to address to use if not specified in the message.
+  */
+  replyTo?: EmailAddress;
+}
+/**
+* Mail class - instance-based email sending.
+*/
+declare class Mail {
+  /**
+  * Extracts error messages from an error object.
+  * @param error Error object to extract messages from.
+  * @returns Array of error messages.
+  * @private
+  */
+  private static extractErrorMessages;
+  private provider;
+  private logger?;
+  private loggerInstance?;
+  private globalConfig?;
+  /**
+  * Creates a new Mail instance with a provider.
+  * @param provider The email provider instance.
+  */
+  constructor(provider: Provider);
+  /**
+  * Sets the logger instance for this mail instance.
+  * @param logger The logger instance (Console) to use for logging.
+  * @returns This instance for method chaining.
+  * @example
+  * ```ts
+  * const mail = createMail(provider);
+  * mail.setLogger(console);
+  * ```
+  */
+  setLogger(logger: Console): this;
+  /**
+  * Sets the default from address for all emails sent through this Mail instance.
+  * @param from Default from address to use if not specified in the message.
+  * @returns This instance for method chaining.
+  * @example
+  * ```ts
+  * const mail = createMail(provider);
+  * mail.setFrom({ email: "noreply@example.com", name: "My App" });
+  * ```
+  */
+  setFrom(from: EmailAddress): this;
+  /**
+  * Sets the default reply-to address for all emails sent through this Mail instance.
+  * @param replyTo Default reply-to address to use if not specified in the message.
+  * @returns This instance for method chaining.
+  * @example
+  * ```ts
+  * const mail = createMail(provider);
+  * mail.setReplyTo({ email: "support@example.com" });
+  * ```
+  */
+  setReplyTo(replyTo: EmailAddress): this;
+  /**
+  * Sets default headers for all emails sent through this Mail instance.
+  * These headers will be merged with message-specific headers, with message headers taking precedence.
+  * @param headers Default headers to add to all emails.
+  * @returns This instance for method chaining.
+  * @example
+  * ```ts
+  * const mail = createMail(provider);
+  * mail.setHeaders({ "X-App-Name": "MyApp", "X-Version": "1.0.0" });
+  * ```
+  */
+  setHeaders(headers: EmailHeaders): this;
+  /**
+  * Creates a draft email in EML (RFC 822) format without sending it.
+  * This is useful for previewing, saving for later, or testing email content.
+  * @param message The message to create a draft from (MailMessage or EmailOptions).
+  * @returns The email in EML (RFC 822) format as a string with X-Unsent: 1 header.
+  * @example
+  * ```ts
+  * // Create a draft from MailMessage
+  * const message = new MailMessage()
+  *   .to("user@example.com")
+  *   .from("sender@example.com")
+  *   .subject("Hello")
+  *   .html("<h1>Hello World</h1>");
+  *
+  * const eml = await mail.draft(message);
+  * console.log("Draft EML:", eml);
+  *
+  * // Save to file
+  * await fs.writeFile("draft.eml", eml);
+  *
+  * // Or send later by parsing the EML back to EmailOptions
+  * ```
+  */
+  draft(message: SendableMessage | DraftMailMessage): Promise<string>;
+  /**
+  * Sends an email message or email options.
+  * @param message The message to send (MailMessage or EmailOptions).
+  * @returns A result object containing the email result or error.
+  * @example
+  * ```ts
+  * // Using MailMessage
+  * const message = new MailMessage()
+  *   .to("user@example.com")
+  *   .from("sender@example.com")
+  *   .subject("Hello")
+  *   .html("<h1>Hello World</h1>");
+  * await mail.send(message);
+  *
+  * // Using EmailOptions
+  * await mail.send({
+  *   to: "user@example.com",
+  *   from: "sender@example.com",
+  *   subject: "Hello",
+  *   html: "<h1>Hello World</h1>"
+  * });
+  * ```
+  */
+  send(message: SendableMessage): Promise<Result<EmailResult>>;
+  /**
+  * Sends multiple messages using the email service.
+  * Returns an async iterable that yields receipts for each sent message.
+  * @example
+  * ```ts
+  * const messages = [
+  *   { from: "sender@example.com", to: "user1@example.com", subject: "Hello 1", html: "<h1>Hello</h1>" },
+  *   { from: "sender@example.com", to: "user2@example.com", subject: "Hello 2", html: "<h1>Hello</h1>" },
+  * ];
+  *
+  * for await (const receipt of mail.sendMany(messages)) {
+  *   if (receipt.successful) {
+  *     console.log("Sent:", receipt.messageId);
+  *   } else {
+  *     console.error("Failed:", receipt.errorMessages);
+  *   }
+  * }
+  * ```
+  * @param messages An iterable of MailMessage instances or email options to send.
+  * @param options Optional parameters for sending.
+  * @param options.signal Abort signal to cancel the operation.
+  * @returns An async iterable that yields receipts for each sent message.
+  */
+  sendMany(messages: Iterable<SendableMessage> | AsyncIterable<SendableMessage>, options?: {
+    signal?: AbortSignal;
+  }): AsyncIterable<Receipt>;
+  /**
+  * Builds email options from a MailMessage instance for draft creation.
+  * Applies global configuration before building to ensure required fields are set.
+  * @param message The MailMessage or DraftMailMessage instance.
+  * @returns Built email options.
+  * @private
+  */
+  private buildDraftFromMessage;
+  /**
+  * Builds email options from EmailOptions for draft creation.
+  * @param options The EmailOptions object.
+  * @returns Email options.
+  * @private
+  */
+  private buildDraftFromOptions;
+  /**
+  * Applies global configuration to a MailMessage instance.
+  * @param message The MailMessage or DraftMailMessage instance.
+  * @private
+  */
+  private applyGlobalConfigToMessage;
+  /**
+  * Applies global configuration to email options.
+  * Global values are only applied if the corresponding field is not already set in the email options.
+  * @param emailOptions The email options to apply global configuration to.
+  * @returns Email options with global configuration applied.
+  * @private
+  */
+  private applyGlobalConfig;
+}
+/**
+* Creates a new Mail instance with a provider.
+* @param provider The email provider instance.
+* @returns A new Mail instance.
+* @example
+* ```ts
+* const mail = createMail(provider);
+* mail.setFrom({ email: "noreply@example.com", name: "My App" });
+* ```
+*/
+declare const createMail: (provider: Provider) => Mail;
+export { type Attachment, type AttachmentDataOptions, type AttachmentOptions, type CalendarEventOptions, type EmailAddress, EmailError, type EmailHeaders, type EmailOptions, type EmailResult, Mail, type MailGlobalConfig, MailMessage, type Priority, type Provider, type Receipt, RequiredOptionError, type Result, type SendableMessage, type TemplateRenderer, createMail, detectMimeType, generateContentId, readFileAsBuffer };