@courierx/client

Official Node.js client for CourierX email delivery API

Installation

npm install @courierx/client

Quick Start

import { CourierXClient } from '@courierx/client';

const client = new CourierXClient({
  apiKey: 'your-api-key'
});

const result = await client.send({
  to: ['[email protected]'],
  from: '[email protected]',
  subject: 'Hello from CourierX',
  html: '<p>Hello World!</p>'
});

console.log(`Email sent: ${result.messageId}`);

Features

• ✅ TypeScript Support - Full type safety and IntelliSense
• ✅ Promise-based API - Modern async/await support
• ✅ Automatic Retries - Built-in retry logic for failures
• ✅ Error Handling - Detailed error messages and status codes
• ✅ HMAC Authentication - Optional request signing
• ✅ Rate Limit Handling - Automatic backoff on limits

Authentication

// API Key (required)
const client = new CourierXClient({
  apiKey: 'your-api-key'
});

// With HMAC signing (optional, enhanced security)
const client = new CourierXClient({
  apiKey: 'your-api-key',
  hmacSecret: 'your-hmac-secret',
  enableHmac: true
});

API Reference

Send Email

const result = await client.send({
  to: ['[email protected]'],           // required
  from: '[email protected]',      // required  
  subject: 'Your Subject',            // required
  html: '<p>HTML content</p>',        // optional
  text: 'Plain text content',         // optional
  attachments: [{                     // optional
    filename: 'document.pdf',
    content: 'base64-content',
    contentType: 'application/pdf'
  }],
  headers: { 'X-Custom': 'value' },   // optional
  tags: ['welcome', 'onboarding'],    // optional
  metadata: { userId: '123' }         // optional
});

Get Account Info

const account = await client.me();
console.log(`Rate limit: ${account.usage.remainingThisHour}/${account.product.rateLimitPerHour}`);

Error Handling

import { CourierXError, RateLimitError, ValidationError } from '@courierx/client';

try {
  await client.send(emailRequest);
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after: ${error.retryAfter}s`);
  } else if (error instanceof ValidationError) {
    console.log(`Validation error: ${error.message}`);
  } else if (error instanceof CourierXError) {
    console.log(`API error: ${error.message} (${error.statusCode})`);
  }
}

Configuration

const client = new CourierXClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.courierx.dev',  // optional
  timeout: 30000,                       // optional (30s)
  retries: 3,                          // optional
  retryDelay: 1000,                    // optional (1s)
  hmacSecret: 'your-hmac-secret',      // optional
  enableHmac: false                    // optional
});

Environment Variables

COURIERX_API_KEY=your-api-key
COURIERX_BASE_URL=https://api.courierx.dev
COURIERX_HMAC_SECRET=your-hmac-secret

// Auto-loads from environment
const client = new CourierXClient();

Examples

With Attachments

import { readFileSync } from 'fs';

const pdfContent = readFileSync('document.pdf').toString('base64');

await client.send({
  to: ['[email protected]'],
  from: '[email protected]',
  subject: 'Your document',
  html: '<p>Document attached.</p>',
  attachments: [{
    filename: 'document.pdf',
    content: pdfContent,
    contentType: 'application/pdf'
  }]
});

Bulk Email

const users = [
  { email: '[email protected]', name: 'John' },
  { email: '[email protected]', name: 'Jane' }
];

for (const user of users) {
  await client.send({
    to: [user.email],
    from: '[email protected]',
    subject: `Hello ${user.name}!`,
    html: `<p>Hello ${user.name}!</p>`,
    metadata: { userId: user.id },
    tags: ['newsletter']
  });
}

TypeScript

Full type safety included:

import type { SendRequest, SendResponse } from '@courierx/client';

const request: SendRequest = { /* ... */ };
const response: SendResponse = await client.send(request);

License

MIT