# Node.js

## 1. Installation

Install the SDK via your preferred package manager:

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

## 2. Send your first email

Initialize the email client with your project token:

```typescript
import { Lettermint } from "lettermint";

const email = Lettermint.email(process.env.LETTERMINT_PROJECT_TOKEN!);
```

Send your first email:

```typescript
const response = await email
  .from('John Doe <john@yourdomain.com>')
  .to('recipient@example.com')
  .subject('Hello from Lettermint')
  .text('This is a test email sent using the Lettermint Node.js SDK.')
  .send();

console.log(`Email sent with ID: ${response.message_id}`);
```

## 3. Email Features

### Basic Email

Send a simple text or HTML email:

```typescript
const response = await email
    .from('John Doe <john@yourdomain.com>')
    .to('recipient@example.com')
    .subject('Your account is ready!')
    .html('<h1>Welcome!</h1><p>Thanks for signing up.</p>')
    .text('Welcome! Thanks for signing up.')
    .send();
```

### Multiple Recipients

Send to multiple recipients using CC and BCC:

```typescript
const response = await email
    .from('John Doe <john@yourdomain.com>')
    .to('user1@example.com', 'user2@example.com')
    .cc('manager@yourdomain.com')
    .bcc('archive@yourdomain.com')
    .subject('Monthly Newsletter')
    .html('<h1>This Month\'s Updates</h1>')
    .send();
```

### Custom Headers and Reply-To

Add custom headers and set reply-to addresses:

```typescript
const response = await email
    .from('support@yourdomain.com')
    .to('customer@example.com')
    .replyTo('help@yourdomain.com')
    .subject('Support Ticket #12345')
    .headers({
        'X-Priority': '1',
        'X-Ticket-ID': '12345'
    })
    .html('<p>Your support ticket has been updated.</p>')
    .send();
```

### Metadata

Add metadata for tracking and webhook payloads:

```typescript
const response = await email
    .from('notifications@yourdomain.com')
    .to('user@example.com')
    .subject('Order Confirmation')
    .metadata({
        'order_id': '12345',
        'customer_id': 'cust_789',
        'campaign': 'order_confirmation'
    })
    .html('<p>Your order has been confirmed.</p>')
    .send();
```

:::note
Metadata is included in webhook payloads but not added to the actual email headers. Use it for tracking and analytics purposes.
:::

### Tags

Categorize emails for filtering and analytics:

```typescript
const response = await email
    .from('alerts@yourdomain.com')
    .to('admin@example.com')
    .subject('System Alert')
    .tag('system-alerts')
    .html('<p>Critical system alert detected.</p>')
    .send();
```

:::note
One tag per message. Tags can contain letters, numbers, hyphens, underscores, and spaces (max 255 characters).
See [Tags documentation](/platform/emails/tags) for more details.
:::

### Route Selection

Direct emails to specific routes within your project:

```typescript
const response = await email
    .from('notifications@yourdomain.com')
    .to('user@example.com')
    .subject('Welcome!')
    .route('transactional')
    .html('<p>Welcome to our platform.</p>')
    .send();
```

### File Attachments

Attach files to your emails:

```typescript
import fs from 'fs';

// Read file content
const fileContent = fs.readFileSync('/path/to/document.pdf');
const base64Content = fileContent.toString('base64');

const response = await email
    .from('invoices@yourdomain.com')
    .to('customer@example.com')
    .subject('Your Invoice')
    .html('<p>Please find your invoice attached.</p>')
    .attach('invoice.pdf', base64Content)
    .send();
```

## 4. Response

```typescript
const response = await email
    .from('John Doe <john@yourdomain.com>')
    .to('recipient@example.com')
    .subject('Test')
    .text('Hello!')
    .send();

console.log(`Email sent with ID: ${response.message_id}`);
console.log(`Status: ${response.status}`);
```

## Next Steps

<CardGroup cols={2}>
    <Card title="Tags" icon="tag" href="/platform/emails/tags">
        Organize and filter emails with tags.
    </Card>
    <Card title="Tracking" icon="chart-line" href="/platform/emails/tracking/introduction">
        Track opens, clicks, and deliverability.
    </Card>
    <Card title="Webhooks" icon="webhook" href="/platform/webhooks/introduction">
        Receive real-time delivery notifications.
    </Card>
    <Card title="SMTP Alternative" icon="envelope" href="/guides/send-email-with-smtp">
        Send via SMTP instead of the API.
    </Card>
</CardGroup>

<Card title="GitHub Repository" icon="github" href="https://github.com/lettermint/lettermint-node">
    Find the complete source code, report issues, or contribute on GitHub.
</Card>