Thanks for signing up.
')
.text('Welcome! Thanks for signing up.')
.send();
```
### Multiple recipients
Send to multiple recipients using CC and BCC:
```typescript
const response = await lettermint.emails
.compose()
.from('John Doe ')
.to('user1@example.com', 'user2@example.com')
.cc('manager@yourdomain.com')
.bcc('archive@yourdomain.com')
.subject('Monthly Newsletter')
.html('This Month\'s Updates
')
.send();
```
### Custom headers and reply-to
Add custom headers and set reply-to addresses:
```typescript
const response = await lettermint.emails
.compose()
.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('Your support ticket has been updated.
')
.send();
```
### Metadata
Add metadata for tracking and webhook payloads:
```typescript
const response = await lettermint.emails
.compose()
.from('notifications@yourdomain.com')
.to('user@example.com')
.subject('Order Confirmation')
.metadata({
'order_id': '12345',
'customer_id': 'cust_789',
'campaign': 'order_confirmation'
})
.html('Your order has been confirmed.
')
.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 lettermint.emails
.compose()
.from('alerts@yourdomain.com')
.to('admin@example.com')
.subject('System Alert')
.tags([
{ name: 'category', value: 'system-alerts' },
{ name: 'environment', value: 'production' }
])
.html('Critical system alert detected.
')
.send();
```
:::note
`tags()` accepts up to 20 name and value pairs. The SDK checks names and values before it sends the request and throws `LettermintValidationError` if one is invalid. `tag()` still sets the existing singular tag, which has no deprecation date. See [Tags documentation](/platform/emails/tags).
:::
### Route selection
Direct emails to specific routes within your project:
```typescript
const response = await lettermint.emails
.compose()
.from('notifications@yourdomain.com')
.to('user@example.com')
.subject('Welcome!')
.route('transactional')
.html('Welcome to our platform.
')
.send();
```
### Idempotency
Pass an idempotency key so a retry never sends the same email twice. If a request with the same key is repeated within the idempotency window, Lettermint returns the original result instead of sending again. The key is an option of the call that sends the email:
```typescript
const response = await lettermint.emails
.compose()
.from('notifications@yourdomain.com')
.to('user@example.com')
.subject('Order Confirmation')
.html('Your order has been confirmed.
')
.send({ idempotencyKey: 'order-confirmation-12345' });
```
`emails.send(message, { idempotencyKey })` and `emails.sendBatch(messages, { idempotencyKey })` take the same option. The key applies only to that call, and the SDK never retries on its own.
:::tip
Derive the key from something stable in your domain, such as an order or invoice ID, so the same business event always maps to the same key. See the [idempotency documentation](/platform/emails/idempotency) for the full behaviour.
:::
### File attachments
Attach files to your emails. `content` is a base64 string, a `Uint8Array` (including a Node.js `Buffer`), or an `ArrayBuffer`. The SDK encodes bytes to base64 for you:
```typescript
import { readFile } from 'node:fs/promises';
const response = await lettermint.emails
.compose()
.from('invoices@yourdomain.com')
.to('customer@example.com')
.subject('Your Invoice')
.html('Please find your invoice attached.
')
.attach({
filename: 'invoice.pdf',
content: await readFile('/path/to/document.pdf'),
contentType: 'application/pdf'
})
.send();
```
To show an attachment inside the HTML body, set `contentId` and reference it as `cid:` in the markup. See [Inline images](/platform/emails/inline-images).
### Batch sending
Send up to 500 emails in one request. The array can mix plain messages and builders:
```typescript
const base = lettermint.emails
.compose()
.from('John Doe ')
.subject('Your weekly summary');
const results = await lettermint.emails.sendBatch([
{ from: 'John Doe ', to: ['user1@example.com'], subject: 'Hi', text: 'Hello' },
base.to('user2@example.com').text('Your summary is ready.'),
], { idempotencyKey: 'weekly-summary-2026-10-05' });
```
## 4. Send an order confirmation
A real transactional send usually pulls several of these features together. This example sends a receipt with an HTML and plain-text body, tags it for analytics, attaches the order and customer IDs as metadata, and uses an idempotency key so a retry never emails the customer twice:
```typescript title="order-confirmation.ts"
import { Lettermint } from "lettermint";
const lettermint = new Lettermint({
sendingToken: process.env.LETTERMINT_PROJECT_TOKEN!,
});
interface Order {
id: string;
number: string;
total: string;
customerEmail: string;
customerId: string;
}
export async function sendOrderConfirmation(order: Order) {
return await lettermint.emails
.compose()
.from('Acme Store ')
.to(order.customerEmail)
.replyTo('support@yourdomain.com')
.subject(`Order ${order.number} confirmed`)
.html(`Thanks for your order
Order ${order.number} totalling ${order.total} is confirmed.
`)
.text(`Thanks for your order. Order ${order.number} totalling ${order.total} is confirmed.`)
.tags([{ name: 'type', value: 'order-confirmation' }])
.metadata({ order_id: order.id, customer_id: order.customerId })
.route('transactional')
.send({ idempotencyKey: `order-confirmation-${order.id}` });
}
```
The `metadata` you attach here travels with every webhook event for the message, so a later delivery or bounce maps straight back to the order in your database.
## 5. Response
```typescript
const response = await lettermint.emails
.compose()
.from('John Doe ')
.to('recipient@example.com')
.subject('Test')
.text('Hello!')
.send();
console.log(`Email sent with ID: ${response.message_id}`);
console.log(`Status: ${response.status}`);
```
## 6. Handle errors
Every error the SDK throws extends `LettermintError`. API errors extend `ApiError`, which carries `status`, `code`, and `message`. Catch the subclasses you want to handle:
```typescript
import { ApiError, RateLimitError, TimeoutError, ValidationError } from "lettermint";
try {
await lettermint.emails.send(message, { idempotencyKey });
} catch (error) {
if (error instanceof ValidationError) {
console.error(error.message, error.errors);
} else if (error instanceof RateLimitError) {
// Wait error.retryAfter seconds, then retry with the same idempotencyKey.
} else if (error instanceof TimeoutError) {
// The outcome is unknown. Retry with the same idempotencyKey.
} else if (error instanceof ApiError) {
console.error(error.status, error.code, error.message);
} else {
throw error;
}
}
```
The SDK never retries on its own. Reuse the same idempotency key when you retry so the customer gets one email. Other errors include `AuthenticationError`, `PermissionError`, `NotFoundError`, `ConflictError`, `ServerError`, `ConnectionError`, `LettermintConfigError` for a missing token, and `LettermintValidationError` when the SDK rejects a request before it sends it.
## Track delivery, opens, and bounces
Sending is only half of a transactional setup. To see what happens after a message leaves your app, combine the SDK with Lettermint's platform features:
- [Email tracking](/platform/emails/tracking/introduction) records opens and clicks, with bot filtering so your metrics stay accurate.
- [Webhooks](/platform/webhooks/introduction) push delivery, bounce, and complaint events to your server in real time, so you can update order records or suppress bad addresses. The SDK verifies each delivery with `new Webhook(secret).verify(rawBody, headers)`. See [Webhook signatures](/platform/webhooks/signing#verify-with-the-nodejs-sdk).
- [Test addresses](/platform/emails/sending-test-emails) let you trigger a hard or soft bounce on demand while you build and verify your webhook handler.
Tracking is configured per route, so turn it on for the route your app sends through, then read the results from your dashboard or your webhook endpoint.
## FAQ
Does the SDK support TypeScript?
Yes. The SDK is written in TypeScript and exports its request and response types, such as `SendMailRequest` and `SendMailResponse`, so every builder method and field is typed and autocompletes in your editor. Query parameters for the Team API are typed objects too, for example `{ page: { size: 30 } }`.
How do I stop the same email being sent twice?
Pass an `idempotencyKey` option to `send()` or `sendBatch()`, derived from a stable ID such as an order number. A repeated request with the same key returns the original result instead of sending again. See the [idempotency documentation](/platform/emails/idempotency).
Is Lettermint email GDPR compliant and EU-hosted?
Yes. Lettermint runs exclusively on European infrastructure and processes email in line with GDPR, so transactional mail from your Node app is handled inside the EU.
How do I track opens, clicks, and bounces?
Enable [tracking](/platform/emails/tracking/introduction) on your route and subscribe to [webhooks](/platform/webhooks/introduction) to receive delivery, open, and bounce events. Use the [test addresses](/platform/emails/sending-test-emails) to simulate bounces while you build your handler.
## Next steps
Organize and filter emails with tags.
Track opens, clicks, and deliverability.
Receive delivery events through webhooks.
Send via SMTP instead of the API.
Find the complete source code, report issues, or contribute on GitHub.