Worker Mailer

https://github.com/zou-yu/worker-mailer
Admin
Worker Mailer is an SMTP client that runs on Cloudflare Workers without dependencies, enabling email...
Tokens:7,642
Snippets:44
Trust Score:6.3
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Dependencies

Source: https://github.com/zou-yu/worker-mailer/blob/main/README.md

Installs project dependencies using pnpm. Ensure pnpm is installed globally.

```bash
pnpm install
```

--------------------------------

### Run Integration Tests

Source: https://github.com/zou-yu/worker-mailer/blob/main/README.md

Starts the development server for integration testing using wrangler. Send POST requests to the specified local address.

```bash
pnpm dlx wrangler dev ./test/worker.ts
```

--------------------------------

### Install Worker Mailer

Source: https://github.com/zou-yu/worker-mailer/blob/main/README.md

Install the worker-mailer package using npm.

```shell
npm i worker-mailer
```

--------------------------------

### Quick Start: Connect and Send Email

Source: https://github.com/zou-yu/worker-mailer/blob/main/README.md

Connect to an SMTP server and send an email using Worker Mailer. Ensure your wrangler.toml is configured.

```typescript
import { WorkerMailer } from 'worker-mailer'

// Connect to SMTP server
const mailer = await WorkerMailer.connect({
  credentials: {
    username: 'bob@acme.com',
    password: 'password',
  },
  authType: 'plain',
  host: 'smtp.acme.com',
  port: 587,
  secure: true,
})

// Send email
await mailer.send({
  from: { name: 'Bob', email: 'bob@acme.com' },
  to: { name: 'Alice', email: 'alice@acme.com' },
  subject: 'Hello from Worker Mailer',
  text: 'This is a plain text message',
  html: '<h1>Hello</h1><p>This is an HTML message</p>',
})
```

--------------------------------

### Cloudflare Worker Mailer Integration Example

Source: https://context7.com/zou-yu/worker-mailer/llms.txt

This example demonstrates how to set up and use Worker Mailer within a Cloudflare Worker. It requires specific environment variables for SMTP configuration and includes basic error handling. Ensure `nodejs_compat` is enabled in your wrangler.toml.

```typescript
// wrangler.toml configuration required:
// compatibility_flags = ["nodejs_compat"]

import { WorkerMailer, LogLevel } from 'worker-mailer'

interface Env {
  SMTP_HOST: string
  SMTP_PORT: string
  SMTP_USERNAME: string
  SMTP_PASSWORD: string
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    if (request.method !== 'POST') {
      return new Response('Method not allowed', { status: 405 })
    }

    try {
      const { to, subject, message } = await request.json() as {
        to: string
        subject: string
        message: string
      }

      const mailer = await WorkerMailer.connect({
        host: env.SMTP_HOST,
        port: parseInt(env.SMTP_PORT),
        secure: false,
        startTls: true,
        credentials: {
          username: env.SMTP_USERNAME,
          password: env.SMTP_PASSWORD
        },
        authType: 'plain',
        logLevel: LogLevel.INFO
      })

      await mailer.send({
        from: { name: 'My App', email: env.SMTP_USERNAME },
        to: to,
        subject: subject,
        text: message,
        html: `<p>${message}</p>`
      })

      await mailer.close()

      return new Response(JSON.stringify({ success: true }), {
        headers: { 'Content-Type': 'application/json' }
      })
    } catch (error) {
      console.error('Email error:', error)
      return new Response(
        JSON.stringify({ error: 'Failed to send email' }),
        { status: 500, headers: { 'Content-Type': 'application/json' } }
      )
    }
  }
}
```

--------------------------------

### WorkerMailer.send() Static Method Example

Source: https://github.com/zou-yu/worker-mailer/blob/main/README.md

Demonstrates sending a one-off email using the static WorkerMailer.send() method. Requires WorkerMailer options and EmailOptions.

```typescript
await WorkerMailer.send(
  {
    // WorkerMailerOptions
    host: 'smtp.acme.com',
    port: 587,
    credentials: {
      username: 'user',
      password: 'pass',
    },
  },
  {
    // EmailOptions
    from: 'sender@acme.com',
    to: 'recipient@acme.com',
    subject: 'Test',
    text: 'Hello',
    attachments: [
      {
        filename: 'test.txt',
        content: 'SGVsbG8gV29ybGQ=', // base64-encoded string for "Hello World"
        type: 'text/plain',
      },
    ],
  },
)
```

--------------------------------

### Integration Test Request Body

Source: https://github.com/zou-yu/worker-mailer/blob/main/README.md

Example JSON payload for integration testing via POST request to the local development server.

```json
{
  "config": {
    "credentials": {
      "username": "xxx@xx.com",
      "password": "xxxx"
    },
    "authType": "plain",
    "host": "smtp.acme.com",
    "port": 587,
    "secure": false,
    "startTls": true
  },
  "email": {
    "from": "xxx@xx.com",
    "to": "yyy@yy.com",
    "subject": "Test Email",
    "text": "Hello World"
  }
}
```

--------------------------------

### Framework Integration with Conditional Imports

Source: https://github.com/zou-yu/worker-mailer/blob/main/README.md

Example for integrating Worker Mailer with modern JavaScript frameworks like Nuxt.js, using conditional dynamic imports for development and production environments.

```typescript
export default defineEventHandler(async event => {
  // Check if running in development environment
  if (import.meta.dev) {
    // Development: Use nodemailer (or any Node.js compatible email library)
    const nodemailer = await import('nodemailer')
    const transporter = nodemailer.default.createTransport()
    return await transporter.sendMail()
  } else {
    // Production: Use worker-mailer in Cloudflare Workers environment
    const { WorkerMailer } = await import('worker-mailer')
    const mailer = await WorkerMailer.connect()
    return await mailer.send()
  }
})
```

--------------------------------

### Run Unit Tests

Source: https://github.com/zou-yu/worker-mailer/blob/main/README.md

Executes the unit tests for the project using npm.

```bash
npm test
```

--------------------------------

### Configuration: LogLevel and Authentication

Source: https://context7.com/zou-yu/worker-mailer/llms.txt

Details on configuring logging verbosity and SMTP authentication methods.

```APIDOC
## LogLevel Enum

### Description
Configures the verbosity of internal logging for debugging SMTP communication.
- **DEBUG** (0): All messages including SMTP protocol details
- **INFO** (1): Connection status and key events (default)
- **WARN** (2): Warnings only
- **ERROR** (3): Errors only
- **NONE** (4): No logging

## Authentication Types

### Description
Worker Mailer supports three SMTP authentication methods: PLAIN, LOGIN, and CRAM-MD5. You can specify a single method or provide an array of preferred methods in priority order.
```

--------------------------------

### WorkerMailer.connect()

Source: https://github.com/zou-yu/worker-mailer/blob/main/README.md

Establishes a connection to an SMTP server. This is the primary method for initializing the Worker Mailer client.

```APIDOC
## WorkerMailer.connect(options)

### Description
Creates a new SMTP connection.

### Method
`WorkerMailer.connect`

### Parameters
#### Request Body
- **options** (WorkerMailerOptions) - Required - Configuration options for the SMTP connection.

```typescript
type WorkerMailerOptions = {
  host: string // SMTP server hostname
  port: number // SMTP server port (usually 587 or 465)
  secure?: boolean // Use TLS (default: false)
  startTls?: boolean // Upgrade to TLS if SMTP server supports (default: true)
  credentials?: {
    // SMTP authentication credentials
    username: string
    password: string
  }
  authType?:
    | 'plain'
    | 'login'
    | 'cram-md5'
    | Array<'plain' | 'login' | 'cram-md5'>
  logLevel?: LogLevel // Logging level (default: LogLevel.INFO)
  socketTimeoutMs?: number // Socket timeout in milliseconds
  responseTimeoutMs?: number // Server response timeout in milliseconds
  dsn?: {
    RET?: {
      HEADERS?: boolean
      FULL?: boolean
    }
    NOTIFY?: {
      DELAY?: boolean
      FAILURE?: boolean
      SUCCESS?: boolean
    }
  }
}
```

### Response
#### Success Response (200)
- **mailer** (WorkerMailer) - An instance of the WorkerMailer client connected to the SMTP server.

#### Response Example
```typescript
const mailer = await WorkerMailer.connect({
  credentials: {
    username: 'bob@acme.com',
    password: 'password',
  },
  authType: 'plain',
  host: 'smtp.acme.com',
  port: 587,
  secure: true,
})
```
```

--------------------------------

### Connect to SMTP Server

Source: https://context7.com/zou-yu/worker-mailer/llms.txt

Initializes a persistent SMTP connection with authentication and configuration options.

```typescript
import { WorkerMailer, LogLevel } from 'worker-mailer'

// Connect to SMTP server with full configuration
const mailer = await WorkerMailer.connect({
  host: 'smtp.example.com',
  port: 587,
  secure: false,                    // Use implicit TLS (port 465)
  startTls: true,                   // Upgrade to TLS via STARTTLS (default: true)
  credentials: {
    username: 'user@example.com',
    password: 'your-password'
  },
  authType: 'plain',                // Options: 'plain', 'login', 'cram-md5', or array
  logLevel: LogLevel.INFO,          // Options: DEBUG, INFO, WARN, ERROR, NONE
  socketTimeoutMs: 60000,           // Socket connection timeout (default: 60s)
  responseTimeoutMs: 30000,         // Server response timeout (default: 30s)
  dsn: {                            // Delivery Status Notification settings
    RET: { HEADERS: true },         // Return headers on bounce
    NOTIFY: {
      SUCCESS: true,
      FAILURE: true,
      DELAY: true
    }
  }
})

// Connection is now ready - send multiple emails
await mailer.send({ /* email options */ })
await mailer.send({ /* another email */ })

// Close connection when done
await mailer.close()
```

--------------------------------

### Configure Wrangler.toml

Source: https://github.com/zou-yu/worker-mailer/blob/main/README.md

Configure your wrangler.toml file to enable Node.js compatibility for Worker Mailer.

```toml
compatibility_flags = ["nodejs_compat"]
```

```toml
# or compatibility_flags = ["nodejs_compat_v2"]
```

--------------------------------

### WorkerMailer.connect(options)

Source: https://context7.com/zou-yu/worker-mailer/llms.txt

Establishes and initializes a new SMTP connection. This method handles the SMTP handshake, capability negotiation, TLS upgrade, and authentication, creating a persistent connection for efficient email sending.

```APIDOC
## WorkerMailer.connect(options)

### Description
Creates and initializes a new SMTP connection to the mail server. This method establishes a persistent connection that can be reused for sending multiple emails efficiently. It handles the SMTP handshake, capability negotiation, TLS upgrade (if configured), and authentication automatically.

### Method
`WorkerMailer.connect`

### Parameters
#### Options Object
- **host** (string) - Required - The SMTP server hostname.
- **port** (number) - Optional - The SMTP server port (default: 25).
- **secure** (boolean) - Optional - Use implicit TLS (port 465). Default is false.
- **startTls** (boolean) - Optional - Upgrade to TLS via STARTTLS. Default is true.
- **credentials** (object) - Required - An object containing `username` and `password` for authentication.
  - **username** (string) - Required - The username for SMTP authentication.
  - **password** (string) - Required - The password for SMTP authentication.
- **authType** (string) - Optional - The authentication method. Options: 'plain', 'login', 'cram-md5', or an array of types. Default is 'plain'.
- **logLevel** (LogLevel) - Optional - The logging level. Options: DEBUG, INFO, WARN, ERROR, NONE. Default is INFO.
- **socketTimeoutMs** (number) - Optional - Socket connection timeout in milliseconds. Default is 60000.
- **responseTimeoutMs** (number) - Optional - Server response timeout in milliseconds. Default is 30000.
- **dsn** (object) - Optional - Delivery Status Notification settings.
  - **RET** (object) - Optional - Specifies what to return on bounce.
    - **HEADERS** (boolean) - Optional - Return headers on bounce.
  - **NOTIFY** (object) - Optional - Specifies when to send notifications.
    - **SUCCESS** (boolean) - Optional - Notify on success.
    - **FAILURE** (boolean) - Optional - Notify on failure.
    - **DELAY** (boolean) - Optional - Notify on delay.

### Request Example
```typescript
import { WorkerMailer, LogLevel } from 'worker-mailer'

const mailer = await WorkerMailer.connect({
  host: 'smtp.example.com',
  port: 587,
  startTls: true,
  credentials: {
    username: 'user@example.com',
    password: 'your-password'
  },
  authType: 'plain',
  logLevel: LogLevel.INFO,
  dsn: {
    RET: { HEADERS: true },
    NOTIFY: {
      SUCCESS: true,
      FAILURE: true,
      DELAY: true
    }
  }
})
```

### Response
#### Success Response (200)
- **mailer** (WorkerMailer) - An instance of the WorkerMailer client with an active connection.
```

--------------------------------

### mailer.send(options)

Source: https://github.com/zou-yu/worker-mailer/blob/main/README.md

Sends an email using the configured mailer instance.

```APIDOC
## mailer.send(options)

### Description
Sends an email using the current mailer instance configuration.

### Parameters
#### Request Body
- **from** (string|object) - Required - Sender's email address or object with name and email.
- **to** (string|string[]|object|array) - Required - Recipient(s) email address(es).
- **reply** (string|object) - Optional - Reply-To address.
- **cc** (string|string[]|object|array) - Optional - Carbon Copy recipients.
- **bcc** (string|string[]|object|array) - Optional - Blind Carbon Copy recipients.
- **subject** (string) - Required - Email subject.
- **text** (string) - Optional - Plain text content.
- **html** (string) - Optional - HTML content.
- **headers** (Record<string, string>) - Optional - Custom email headers.
- **attachments** (array) - Optional - List of attachments with filename, content (base64), and mimeType.
- **dsnOverride** (object) - Optional - Delivery Status Notification overrides.
```

--------------------------------

### Configure SMTP Authentication Types

Source: https://context7.com/zou-yu/worker-mailer/llms.txt

Specify 'plain', 'login', or 'cram-md5' for authentication. You can provide a single type or an array for preferred order.

```typescript
import { WorkerMailer } from 'worker-mailer'

// Single auth type
const mailer1 = await WorkerMailer.connect({
  host: 'smtp.example.com',
  port: 587,
  credentials: { username: 'user@example.com', password: 'password' },
  authType: 'plain'  // Most common, sends credentials base64-encoded
})

// LOGIN authentication (legacy servers)
const mailer2 = await WorkerMailer.connect({
  host: 'smtp.legacy-server.com',
  port: 587,
  credentials: { username: 'user@example.com', password: 'password' },
  authType: 'login'  // Username and password sent separately
})

// CRAM-MD5 (challenge-response, more secure)
const mailer3 = await WorkerMailer.connect({
  host: 'smtp.secure-server.com',
  port: 587,
  credentials: { username: 'user@example.com', password: 'password' },
  authType: 'cram-md5'  // Password never sent over wire
})

// Multiple auth types - tries in order based on server support
const mailer4 = await WorkerMailer.connect({
  host: 'smtp.example.com',
  port: 587,
  credentials: { username: 'user@example.com', password: 'password' },
  authType: ['cram-md5', 'plain', 'login']  // Prefers CRAM-MD5 if available
})
```

--------------------------------

### Create Feature Branch

Source: https://github.com/zou-yu/worker-mailer/blob/main/README.md

Creates a new git branch for feature development from the 'develop' branch.

```bash
git checkout -b feat/your-feature-name
```

--------------------------------

### mailer.send()

Source: https://github.com/zou-yu/worker-mailer/blob/main/README.md

Sends an email using the established SMTP connection.

```APIDOC
## mailer.send(options)

### Description
Sends an email using the established SMTP connection.

### Method
`mailer.send`

### Parameters
#### Request Body
- **options** (SendMailOptions) - Required - Options for sending the email.

```typescript
type SendMailOptions = {
  from: {
    name?: string
    email: string
  }
  to: {
    name?: string
    email: string
  } | Array<{
    name?: string
    email: string
  }> // Supports 'to', 'cc', 'bcc'
  subject: string
  text?: string // Plain text body
  html?: string // HTML body
  attachments?: Array<{
    filename: string
    content: string | Buffer
    contentType?: string
    cid?: string // For inline images
  }> 
}
```

### Response
#### Success Response (200)
- **messageId** (string) - The unique message ID of the sent email.

#### Response Example
```typescript
await mailer.send({
  from: { name: 'Bob', email: 'bob@acme.com' },
  to: { name: 'Alice', email: 'alice@acme.com' },
  subject: 'Hello from Worker Mailer',
  text: 'This is a plain text message',
  html: '<h1>Hello</h1><p>This is an HTML message</p>',
  attachments: [
    {
      filename: 'notes.txt',
      content: 'Some notes here',
    },
  ],
})
```
```

--------------------------------

### Configure Logging Verbosity with LogLevel

Source: https://context7.com/zou-yu/worker-mailer/llms.txt

Set the logLevel option during connection to control internal logging. DEBUG shows all SMTP details, while ERROR or NONE are suitable for production.

```typescript
import { WorkerMailer, LogLevel } from 'worker-mailer'

// Available log levels (in order of verbosity)
// LogLevel.DEBUG = 0  - All messages including SMTP protocol details
// LogLevel.INFO  = 1  - Connection status and key events (default)
// LogLevel.WARN  = 2  - Warnings only
// LogLevel.ERROR = 3  - Errors only
// LogLevel.NONE  = 4  - No logging

// Debug mode for troubleshooting SMTP issues
const mailer = await WorkerMailer.connect({
  host: 'smtp.example.com',
  port: 587,
  credentials: { username: 'user@example.com', password: 'password' },
  authType: 'plain',
  logLevel: LogLevel.DEBUG  // Shows all SMTP commands and responses
})

// Production mode - minimal logging
const prodMailer = await WorkerMailer.connect({
  host: 'smtp.example.com',
  port: 587,
  credentials: { username: 'user@example.com', password: 'password' },
  authType: 'plain',
  logLevel: LogLevel.ERROR  // Only log errors
})
```

--------------------------------

### Send Email via SMTP

Source: https://context7.com/zou-yu/worker-mailer/llms.txt

Sends an email using an established connection, supporting attachments, custom headers, and DSN overrides.

```typescript
import { WorkerMailer } from 'worker-mailer'

const mailer = await WorkerMailer.connect({
  host: 'smtp.example.com',
  port: 587,
  credentials: { username: 'sender@example.com', password: 'password' },
  authType: 'plain'
})

// Send email with all options
await mailer.send({
  // Sender - string or object format
  from: { name: 'John Doe', email: 'john@example.com' },

  // Recipients - supports string, array, or object format
  to: [
    { name: 'Alice Smith', email: 'alice@example.com' },
    'bob@example.com'
  ],

  // Optional CC and BCC recipients
  cc: { name: 'Manager', email: 'manager@example.com' },
  bcc: ['audit@example.com', 'archive@example.com'],

  // Reply-To address
  reply: { name: 'Support Team', email: 'support@example.com' },

  // Subject line
  subject: 'Monthly Report - March 2024',

  // Content - at least one of text or html required
  text: 'Please find the monthly report attached.',
  html: `
    <h1>Monthly Report</h1>
    <p>Please find the monthly report attached.</p>
    <p>Best regards,<br>John</p>
  `,

  // Custom headers
  headers: {
    'X-Priority': '1',
    'X-Custom-Header': 'custom-value'
  },

  // Attachments - content must be base64-encoded
  attachments: [
    {
      filename: 'report.pdf',
      content: 'JVBERi0xLjQK...',  // Base64-encoded PDF content
      mimeType: 'application/pdf'   // Optional, auto-detected from extension
    },
    {
      filename: 'data.csv',
      content: 'bmFtZSxlbWFpbA==', // Base64-encoded CSV content
    }
  ],

  // Override DSN settings for this specific email
  dsnOverride: {
    envelopeId: 'unique-tracking-id-123',
    NOTIFY: { SUCCESS: true, FAILURE: true }
  }
})

await mailer.close()
```

--------------------------------

### mailer.send(options)

Source: https://context7.com/zou-yu/worker-mailer/llms.txt

Sends an email through the established SMTP connection. This method queues the email and returns a promise that resolves when the email is successfully accepted by the SMTP server.

```APIDOC
## mailer.send(options)

### Description
Sends an email through the established SMTP connection. This method queues the email and returns a promise that resolves when the email is successfully accepted by the SMTP server. It supports plain text, HTML content, attachments, and multiple recipients with proper MIME encoding.

### Method
`mailer.send`

### Parameters
#### Options Object
- **from** (string | object) - Required - The sender's email address and optional name.
  - **name** (string) - Optional - The sender's name.
  - **email** (string) - Required - The sender's email address.
- **to** (string | array | object) - Required - Recipients' email addresses and optional names.
  - **name** (string) - Optional - The recipient's name.
  - **email** (string) - Required - The recipient's email address.
- **cc** (string | array | object) - Optional - CC recipients.
- **bcc** (string | array | object) - Optional - BCC recipients.
- **reply** (object) - Optional - The Reply-To address.
  - **name** (string) - Optional - The reply name.
  - **email** (string) - Required - The reply email address.
- **subject** (string) - Required - The email subject line.
- **text** (string) - Optional - The plain text content of the email.
- **html** (string) - Optional - The HTML content of the email.
- **headers** (object) - Optional - Custom email headers.
- **attachments** (array) - Optional - An array of attachment objects.
  - **filename** (string) - Required - The name of the attachment file.
  - **content** (string) - Required - The base64-encoded content of the attachment.
  - **mimeType** (string) - Optional - The MIME type of the attachment (auto-detected).
- **dsnOverride** (object) - Optional - Override DSN settings for this specific email.
  - **envelopeId** (string) - Optional - A unique identifier for tracking the email.
  - **NOTIFY** (object) - Optional - Specifies when to send notifications.
    - **SUCCESS** (boolean) - Optional - Notify on success.
    - **FAILURE** (boolean) - Optional - Notify on failure.
    - **DELAY** (boolean) - Optional - Notify on delay.

### Request Example
```typescript
await mailer.send({
  from: { name: 'John Doe', email: 'john@example.com' },
  to: [
    { name: 'Alice Smith', email: 'alice@example.com' },
    'bob@example.com'
  ],
  cc: { name: 'Manager', email: 'manager@example.com' },
  bcc: ['audit@example.com', 'archive@example.com'],
  reply: { name: 'Support Team', email: 'support@example.com' },
  subject: 'Monthly Report - March 2024',
  text: 'Please find the monthly report attached.',
  html: `<h1>Monthly Report</h1><p>Please find the monthly report attached.</p><p>Best regards,<br>John</p>`,
  headers: {
    'X-Priority': '1',
    'X-Custom-Header': 'custom-value'
  },
  attachments: [
    {
      filename: 'report.pdf',
      content: 'JVBERi0xLjQK...',  // Base64-encoded PDF content
      mimeType: 'application/pdf'
    },
    {
      filename: 'data.csv',
      content: 'bmFtZSxlbWFpbA=='
    }
  ],
  dsnOverride: {
    envelopeId: 'unique-tracking-id-123',
    NOTIFY: { SUCCESS: true, FAILURE: true }
  }
})
```

### Response
#### Success Response (200)
- **messageId** (string) - The unique message ID assigned by the SMTP server.
```

--------------------------------

### Send Single Email with WorkerMailer.send

Source: https://context7.com/zou-yu/worker-mailer/llms.txt

Use this static method for one-off email sends. It automatically handles connection and disconnection. Ideal for serverless environments.

```typescript
import { WorkerMailer } from 'worker-mailer'

// Send a one-off email with auto-connect and auto-close
await WorkerMailer.send(
  // Connection options
  {
    host: 'smtp.example.com',
    port: 587,
    secure: false,
    startTls: true,
    credentials: {
      username: 'sender@example.com',
      password: 'your-password'
    },
    authType: 'plain'
  },
  // Email options
  {
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Welcome to Our Service',
    text: 'Thank you for signing up!',
    html: '<h1>Welcome!</h1><p>Thank you for signing up!</p>'
  }
)
```

--------------------------------

### mailer.close

Source: https://context7.com/zou-yu/worker-mailer/llms.txt

Gracefully terminates the SMTP connection.

```APIDOC
## mailer.close(error?)

### Description
Gracefully closes the SMTP connection by sending the QUIT command. If called with an error parameter, it will reject all pending emails in the queue with that error.

### Parameters
- **error** (Error) - Optional - Error object to reject pending emails with.
```

--------------------------------

### WorkerMailer.send()

Source: https://github.com/zou-yu/worker-mailer/blob/main/README.md

Static method to send a one-off email without maintaining a persistent connection.

```APIDOC
## WorkerMailer.send()

### Description
Send a one-off email without maintaining the connection.

### Request Example
await WorkerMailer.send(
  {
    host: 'smtp.acme.com',
    port: 587,
    credentials: {
      username: 'user',
      password: 'pass',
    },
  },
  {
    from: 'sender@acme.com',
    to: 'recipient@acme.com',
    subject: 'Test',
    text: 'Hello',
    attachments: [
      {
        filename: 'test.txt',
        content: 'SGVsbG8gV29ybGQ=',
        type: 'text/plain',
      },
    ],
  },
)
```

--------------------------------

### EmailOptions Type Definition

Source: https://github.com/zou-yu/worker-mailer/blob/main/README.md

Defines the structure for email options, including sender, recipients, subject, content, and attachments. Ensure attachment content is base64-encoded.

```typescript
type EmailOptions = {
  from:
    | string
    | {
        // Sender's email
        name?: string
        email: string
      }
  to:
    | string
    | string[]
    | {
        // Recipients (TO)
        name?: string
        email: string
      }
    | Array<{ name?: string; email: string }>
  reply?:
    | string
    | {
        // Reply-To address
        name?: string
        email: string
      }
  cc?:
    | string
    | string[]
    | {
        // Carbon Copy recipients
        name?: string
        email: string
      }
    | Array<{ name?: string; email: string }>
  bcc?:
    | string
    | string[]
    | {
        // Blind Carbon Copy recipients
        name?: string
        email: string
      }
    | Array<{ name?: string; email: string }>
  subject: string // Email subject
  text?: string // Plain text content
  html?: string // HTML content
  headers?: Record<string, string> // Custom email headers
  attachments?: { filename: string; content: string; mimeType?: string }[] // Attachments, content must be base64-encoded, it will try to infer mimeType if not set
  dsnOverride?: // overrides dsn defined in WorkerMailer, if not set, it will take the WorkerMailer-Option.
  {
    envelopeId?: string | undefined
    RET?: {
      HEADERS?: boolean
      FULL?: boolean
    }
    NOTIFY?: {
      DELAY?: boolean
      FAILURE?: boolean
      SUCCESS?: boolean
    }
  }
}
```

--------------------------------

### Gracefully Close Mailer Connection

Source: https://context7.com/zou-yu/worker-mailer/llms.txt

Always call mailer.close() when finished sending emails to release resources. If an error is provided, pending emails will be rejected.

```typescript
import { WorkerMailer } from 'worker-mailer'

const mailer = await WorkerMailer.connect({
  host: 'smtp.example.com',
  port: 587,
  credentials: { username: 'user@example.com', password: 'password' },
  authType: 'plain'
})

try {
  await mailer.send({
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Test Email',
    text: 'Hello World'
  })
} catch (error) {
  console.error('Failed to send email:', error)
} finally {
  // Always close the connection
  await mailer.close()
}
```

--------------------------------

### WorkerMailerOptions Type Definition

Source: https://github.com/zou-yu/worker-mailer/blob/main/README.md

Defines the options available for the WorkerMailer.connect method, including host, port, security, credentials, authentication type, and timeouts.

```typescript
type WorkerMailerOptions = {
  host: string // SMTP server hostname
  port: number // SMTP server port (usually 587 or 465)
  secure?: boolean // Use TLS (default: false)
  startTls?: boolean // Upgrade to TLS if SMTP server supports (default: true)
  credentials?: {
    // SMTP authentication credentials
    username: string
    password: string
  }
  authType?:
    | 'plain'
    | 'login'
    | 'cram-md5'
    | Array<'plain' | 'login' | 'cram-md5'>
  logLevel?: LogLevel // Logging level (default: LogLevel.INFO)
  socketTimeoutMs?: number // Socket timeout in milliseconds
  responseTimeoutMs?: number // Server response timeout in milliseconds
  dsn?: {
    RET?: {
      HEADERS?: boolean
      FULL?: boolean
    }
    NOTIFY?: {
      DELAY?: boolean
      FAILURE?: boolean
      SUCCESS?: boolean
    }
  }
}
```

--------------------------------

### WorkerMailer.send

Source: https://context7.com/zou-yu/worker-mailer/llms.txt

Sends a single email by automatically connecting to the SMTP server and closing the connection upon completion.

```APIDOC
## WorkerMailer.send(options, email)

### Description
Static convenience method to send a single email without maintaining a persistent connection. This method connects to the SMTP server, sends the email, and automatically closes the connection.

### Parameters
#### Request Body
- **options** (object) - Required - SMTP connection configuration (host, port, secure, startTls, credentials, authType)
- **email** (object) - Required - Email content (from, to, subject, text, html)

### Request Example
{
  "options": {
    "host": "smtp.example.com",
    "port": 587,
    "credentials": { "username": "user@example.com", "password": "pass" }
  },
  "email": {
    "from": "sender@example.com",
    "to": "recipient@example.com",
    "subject": "Hello",
    "text": "World"
  }
}
```
Tokens:
Raw