# Nodemailer

:::info
This guide covers SMTP integration. For full configuration options and available headers, see the [SMTP Introduction](/guides/send-email-with-smtp).
:::

## Installation

Install nodemailer via your package manager:

<CodeTabs>
    ```bash title="npm"
    npm install nodemailer
    ```
    ```bash title="yarn"
    yarn add nodemailer
    ```
    ```bash title="pnpm"
    pnpm install nodemailer
    ```
    ```bash title="bun"
    bun install nodemailer
    ```
</CodeTabs>

## Basic Configuration

Use environment variables for credentials:

```javascript
const SMTP_HOST = 'smtp.lettermint.co';
const SMTP_USERNAME = 'lettermint';
const API_TOKEN = process.env.LETTERMINT_PROJECT_TOKEN;
```

<CodeTabs>
```javascript title="Port 587 (STARTTLS)"
const nodemailer = require('nodemailer');

const transporter = nodemailer.createTransport({
  host: 'smtp.lettermint.co',
  port: 587,
  secure: false, // STARTTLS
  auth: {
    user: 'lettermint',
    pass: process.env.LETTERMINT_PROJECT_TOKEN,
  },
});

async function sendEmail() {
  try {
    const info = await transporter.sendMail({
      from: 'sender@yourdomain.com',
      to: 'recipient@example.com',
      subject: 'Test Email',
      text: 'Hello! This is a test email.',
      html: '<h1>Hello!</h1><p>This is a test email.</p>',
    });

    console.log('Message sent:', info.messageId);
  } catch (error) {
    console.error('Error sending email:', error);
  }
}

sendEmail();
```

```javascript title="Port 465 (Implicit TLS)"
const nodemailer = require('nodemailer');

const transporter = nodemailer.createTransport({
  host: 'smtp.lettermint.co',
  port: 465,
  secure: true, // Implicit TLS
  auth: {
    user: 'lettermint',
    pass: process.env.LETTERMINT_PROJECT_TOKEN,
  },
});

async function sendEmail() {
  try {
    const info = await transporter.sendMail({
      from: 'sender@yourdomain.com',
      to: 'recipient@example.com',
      subject: 'Test Email',
      text: 'Hello! This is a test email.',
      html: '<h1>Hello!</h1><p>This is a test email.</p>',
    });

    console.log('Message sent:', info.messageId);
  } catch (error) {
    console.error('Error sending email:', error);
  }
}

sendEmail();
```
</CodeTabs>

## Advanced Features

### Multiple Recipients

```javascript
const mailOptions = {
  from: 'sender@yourdomain.com',
  to: ['user1@example.com', 'user2@example.com'],
  cc: 'manager@yourdomain.com',
  bcc: 'archive@yourdomain.com',
  subject: 'Newsletter',
  html: '<h1>Monthly Update</h1>',
};
```

### Attachments

```javascript
const mailOptions = {
  from: 'sender@yourdomain.com',
  to: 'recipient@example.com',
  subject: 'Document Attached',
  html: '<p>Please find the document attached.</p>',
  attachments: [
    {
      filename: 'document.pdf',
      path: './files/document.pdf',
    },
    {
      filename: 'data.json',
      content: JSON.stringify({ key: 'value' }),
    },
  ],
};
```

### Custom Headers

```javascript
const mailOptions = {
  from: 'sender@yourdomain.com',
  to: 'recipient@example.com',
  subject: 'Custom Headers',
  html: '<p>Email with custom headers.</p>',
  headers: {
    'X-Priority': '1',
    'X-Custom-Header': 'Custom Value',
  },
};
```

### Metadata for Tracking

Add metadata that will be included in webhook payloads:

```javascript
const mailOptions = {
  from: 'sender@yourdomain.com',
  to: 'recipient@example.com',
  subject: 'Order Confirmation',
  html: '<p>Your order has been confirmed.</p>',
  headers: {
    'X-LM-Metadata-order_id': '12345',
    'X-LM-Metadata-customer_id': 'cust_789',
    'X-LM-Metadata-campaign': 'order_confirmation',
  },
};
```

### Lettermint Headers

Add Lettermint-specific headers for tags, metadata, and routing:

```javascript
const mailOptions = {
  from: 'sender@yourdomain.com',
  to: 'recipient@example.com',
  subject: 'Order Confirmation',
  html: '<p>Your order has been confirmed.</p>',
  headers: {
    // Tag for categorization
    'X-LM-Tag': 'order-confirmation',
    // Metadata for tracking (included in webhooks)
    'X-LM-Metadata-order_id': '12345',
    'X-LM-Metadata-customer_id': 'cust_789',
    // Route selection
    'X-Lettermint-Route': 'transactional',
  },
};
```

:::note
Metadata headers are extracted by Lettermint and included in webhook payloads, but not added to the actual email sent to recipients.
See the [SMTP Introduction](/guides/send-email-with-smtp#custom-headers) for full details on available headers.
:::