Getting Started

Getting started with mailchannels-sdk

Overview

This library provides a simple way to interact with the MailChannels Email API. It is written in TypeScript and can be used in both JavaScript and TypeScript projects and in different runtimes.

Features

This SDK fully supports all features and operations available in the MailChannels Email API. It is actively maintained to ensure compatibility and to quickly add support for new API features as they are released.

Some of the things you can do with the SDK:

• Send transactional emails
• Check DKIM, SPF & Domain Lockdown
• Configure DKIM keys
• Webhook notifications
• Manage sub-accounts
• Retrieve metrics
• Inspect webhook delivery batches
• Handle suppressions
• Run a local simulator for development testing

TIP

For a detailed reference mapping each SDK method to its corresponding MailChannels API endpoint reference, see the SDK-API Mapping

Prerequisites

• Create a MailChannels account
• Create an API key

Installation

Add mailchannels-sdk dependency to your project

npm

npm i mailchannels-sdk

yarn

yarn add mailchannels-sdk

pnpm

pnpm add mailchannels-sdk

bun

bun add mailchannels-sdk

deno

deno add npm:mailchannels-sdk

Quick Start

This library can be used in two ways:

• Importing the whole library
• Importing the client and only the modules you need

Importing the whole library

In this example, we import the whole library and use the MailChannels class to send an email.

import { MailChannels } from 'mailchannels-sdk'

const mailchannels = new MailChannels('your-api-key')

const { data, error } = await mailchannels.emails.send({
  from: 'Name <from@example.com>',
  to: 'to@example.com',
  subject: 'Test email',
  html: '<p>Hello World</p>'
})

This approach is useful when building an application on top of MailChannels and you need to use all or multiple modules from the library.

Importing only the modules you need

In this example, we import the MailChannelsClient and the Emails module to send an email.

import { MailChannelsClient, Emails } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const emails = new Emails(mailchannels)

const { data, error } = await emails.send({
  from: 'Name <from@example.com>',
  to: 'to@example.com',
  subject: 'Test email',
  html: '<p>Hello World</p>'
})

This approach is tree-shakable and is useful when you only need to use specific modules from the library and want to reduce the bundle size of your application.

Client Options

Both MailChannels and MailChannelsClient accept an optional second argument to configure the client.

import { MailChannels } from 'mailchannels-sdk'

const mailchannels = new MailChannels('your-api-key', {
  baseUrl: 'http://localhost:8787', // default: 'https://api.mailchannels.net'
  retry: 1, // default: false (no retries)
  timeout: 30000, // default: 120000 (120 seconds)
  signal: undefined // default: undefined (no abort signal)
})

• baseUrl string optional: Override the MailChannels client base URL. Useful for local testing against a simulator.
• retry number | false optional: Number of times to retry a request on failure.

  NOTE

  Retries apply only to the following status codes:

  408, 409, 425, 429, 500, 502, 503, 504.

  See ofetch documentation for more details on retry behavior.

• timeout number | false optional: Request timeout in milliseconds. Set to false or 0 to disable timeout handling. Default is 120000 (120 seconds/2 minutes).
• signal AbortSignal optional: Abort signal applied to requests made by the client.

Type declaration

interface MailChannelsClientOptions {
  baseUrl?: string;
  retry?: number | false;
  timeout?: number | false;
  signal?: AbortSignal;
}

Error handling

All methods in this SDK return an object with both data and error properties to avoid throwing exceptions, making error handling more predictable and easier to manage.

Success case:

• data: Contains the response data
• error: Will be null

Error case:

• data: Will be null
• error: Contains an ErrorResponse object with the following properties:
  • message: A human-readable description of the error
  • statusCode: The HTTP status code from the API (e.g., 400, 404), or null if the error is not related to an HTTP request
  • type: A string identifier for the type of error

import { MailChannels } from 'mailchannels-sdk'

const mailchannels = new MailChannels('your-api-key')

const { data, error } = await mailchannels.emails.send({
  from: 'sender@example.com',
  to: 'recipient@example.com',
  subject: 'Test email',
  html: '<p>Hello World</p>'
})

// handle the error as needed
if (error) {
  throw new Error(error.message)
}

// data is guaranteed to be non-null here
console.log({ data })

Naming Conventions

Most properties in the MailChannels API use snake_case. To follow JavaScript conventions, the SDK adopts camelCase for all properties. This means:

• Most options and responses match the API docs, but field names are camelCase rather than snake_case.
• Some fields are grouped into nested objects or renamed for simplicity and better developer experience.
• While most fields match the API docs (just with camelCase), a few may be simplified or reorganized to feel more natural for JavaScript developers.