Local Simulator

This package includes a local MailChannels simulator you can run via the CLI. It holds state in memory and emulates the SDK-supported endpoints, letting you develop and test your application locally without hitting the real MailChannels service.

API	Source
Email API	src/simulator/email-api.mjs

IMPORTANT

The simulator approximates the MailChannels service for local development and testing. It is not a production implementation and may differ from the live service.

Start the simulator

# default: http://127.0.0.1:8787
npx mailchannels-sdk simulate

Options

Option	Description	Default
--port <number>	Port to listen on	8787
--host <host>	Host address	127.0.0.1
--silent	Suppress simulator logs	false

You can override the bind address with the --host and --port options:

npx mailchannels-sdk simulate --host 127.0.0.1 --port 8787

Disable logs with the --silent option:

npx mailchannels-sdk simulate --silent

Point the SDK at the simulator

Use the optional baseUrl constructor option when creating the client:

import { MailChannels } from 'mailchannels-sdk'

const mailchannels = new MailChannels('local-test-key', {
  baseUrl: 'http://127.0.0.1:8787'
})

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

What the simulator supports today

• Email sends and async sends
• Domain checks
• DKIM key create, list, rotate, and update
• Webhook enrollment, listing, validation, signing key lookup, and batch inspection
• Sub-account lifecycle, API keys, SMTP passwords, limits, and usage
• Engagement, performance, recipient behaviour, sender, volume, and usage metrics
• Suppression create, list, and delete

Current limitations

• State is in-memory only and is reset when the process stops
• Any non-empty X-API-Key is accepted, with separate in-memory state per API key
• Webhook responses are simulated locally, but the simulator does not yet emit real webhook callbacks to your application

The next planned expansion is outbound webhook delivery so client applications can test webhook ingestion flows against the simulator as well.