Scaleway Transactional Email (TEM) Node.js Library

A clean, type-safe, and fluent Node.js library for sending emails via Scaleway's Transactional Email (TEM) service. It also supports the Strategy Pattern to allow switching between different email providers (e.g., SMTP/Mailpit for testing).

Features

• 🚀 Fluent Builder Pattern: Easily construct complex emails.
• 🛡️ Type-Safe: Written in TypeScript with full type definitions.
• 🔌 Strategy Pattern: Switch between Scaleway TEM and SMTP (e.g., Mailpit) easily.
• 🛠️ Utilities: Helper functions like fileToBase64 for easy attachment handling.
• 🌍 Scaleway Specific: Tailored for Scaleway's TEM API (v1alpha1).

Table of Contents

• Prerequisites
• Installation
• Configuration
  • Scaleway TEM
  • SMTP (Development/Testing)
• Usage
  • 1. Initialize the Client
  • 2. Build and Send an Email
  • 3. Advanced Usage
• API Reference
  • EmailClient
  • EmailBuilder
  • Transporters
• Error Handling
• Contributing
• License

Prerequisites

• Node.js >= 18.0.0
• A Scaleway account with Transactional Email activated (for production use).

Installation

npm install scaleway-tem-node
# or
yarn add scaleway-tem-node
# or
pnpm add scaleway-tem-node

Configuration

Scaleway TEM

To use Scaleway's Transactional Email service, you need a ScalewayTransporter.

import { ScalewayTransporter } from 'scaleway-tem-node';

const transporter = new ScalewayTransporter({
  secretKey: process.env.SCW_SECRET_KEY, // Your Scaleway Secret Key
  projectId: process.env.SCW_DEFAULT_PROJECT_ID, // Your Project ID
  region: 'fr-par', // Optional: defaults to 'fr-par'
});

SMTP (Development/Testing)

For local development or testing, you can use the SmtpTransporter. This is compatible with tools like Mailpit or any standard SMTP server.

import { SmtpTransporter } from 'scaleway-tem-node';

const transporter = new SmtpTransporter({
  host: 'localhost',
  port: 1025,
  // secure: false, // true for 465, false for other ports
  // auth: {
  //   user: 'user',
  //   pass: 'pass',
  // },
});

Usage

1. Initialize the Client

Pass your configured transporter to the EmailClient.

import { EmailClient, ScalewayTransporter } from 'scaleway-tem-node';

const transporter = new ScalewayTransporter({ /* config */ });
const client = new EmailClient(transporter);

2. Build and Send an Email

Use the EmailBuilder to construct your email.

import { EmailBuilder, fileToBase64 } from 'scaleway-tem-node';

async function sendEmail() {
  // Helper to read file as base64
  const pdfContent = await fileToBase64('./invoice.pdf');

  const email = new EmailBuilder()
    .setFrom('[email protected]', 'My Service')
    .addTo('[email protected]', 'John Doe')
    .setSubject('Your Invoice')
    .setText('Please find your invoice attached.')
    .setHtml('<p>Please find your <b>invoice</b> attached.</p>')
    .addAttachment('invoice.pdf', 'application/pdf', pdfContent)
    .build();

  const result = await client.sendEmail(email);
  console.log('Email sent with ID:', result.id);
}

3. Advanced Usage

The builder supports CC, BCC, custom headers, and scheduling.

const email = new EmailBuilder()
  .setFrom('[email protected]')
  .addTo('[email protected]')
  .addCc('[email protected]')
  .addBcc('[email protected]')
  .addHeader('X-Custom-ID', '12345')
  .setSendBefore(new Date(Date.now() + 3600 * 1000)) // Send before 1 hour from now
  .build();

API Reference

EmailClient

The main entry point for sending emails.

• constructor(transporter: EmailTransporter)
• sendEmail(email: DraftEmail | CreateEmailRequest): Promise<Email>
  • Sends the email using the configured transporter.
• setTransporter(transporter: EmailTransporter): void
  • Switch the transporter at runtime (e.g., based on environment).

EmailBuilder

A fluent interface for creating email objects.

• setFrom(email: string, name?: string): Set sender.
• addTo(email: string, name?: string): Add primary recipient.
• addCc(email: string, name?: string): Add carbon copy recipient.
• addBcc(email: string, name?: string): Add blind carbon copy recipient.
• setSubject(subject: string): Set email subject.
• setText(text: string): Set plain text content.
• setHtml(html: string): Set HTML content.
• addAttachment(name: string, type: string, content: string): Add attachment (content must be Base64).
• addHeader(key: string, value: string): Add custom header.
• setSendBefore(date: Date): Set expiration time (Scaleway specific).
• build(): DraftEmail: Returns the constructed email object.

Transporters

ScalewayTransporter

• Implements EmailTransporter.
• Uses Scaleway's REST API.
• Config: { secretKey: string; projectId: string; region?: 'fr-par' }

SmtpTransporter

• Implements EmailTransporter.
• Uses nodemailer under the hood.
• Config: Standard Nodemailer SMTP transport options (host, port, auth, etc.).

Error Handling

The library throws errors if the API call fails or validation fails.

try {
  await client.sendEmail(email);
} catch (error) {
  if (error instanceof Error) {
    console.error('Error message:', error.message);
  }
  // Scaleway specific errors might contain more details in the message
}

Contributing

Contributions are welcome!

1. Clone the repository.
2. Install dependencies: npm install
3. Run tests: npm test
4. Build: npm run build

License

MIT