@mailchannels/node-red-mailchannels 0.1.0
Send transactional email with the MailChannels Email API from Node-RED.
MailChannels for Node-RED
Send transactional email through the MailChannels Email API. This package provides a mailchannels-send node and a reusable mailchannels-account credential configuration.
Support
This project is supported by the MailChannels team on a best-effort basis. The best way to get support is to file an issue on GitHub: https://github.com/mailchannels/node-red-mailchannels/issues
If you are a MailChannels customer and have a problem with the operation of the MailChannels service, you can get support at https://support.mailchannels.com/
Install
Requires Node.js 22 or later and Node-RED 4 or later. Install @mailchannels/node-red-mailchannels from the editor's Manage palette, or run npm install @mailchannels/node-red-mailchannels from your Node-RED user directory and restart Node-RED. Import the example from the editor's Examples menu.
Status
Version 0.1.0 is the first public release. Runtime behavior is tested with Node-RED 4.1.8 and 5.0.7 with mocked HTTP responses and real loopback TLS fixtures. The example flow, send configuration dialog, dry-run default, and password credential field were verified in the Node-RED 5.0.7 editor. On 2026-10-31 the node passed a live dry-run against the MailChannels Email API in Node-RED 5.0.7 (HTTP 200, nothing sent).
Configure
- Create a MailChannels account and API key with the
apiscope. Follow the setup guide for Domain Lockdown and domain authentication. - Add a MailChannels email node. Create its account configuration and enter the key in the password field. Node-RED stores credentials separately from exported flows; configure its credential encryption and protect access to your editor.
- Set default sender and recipient addresses, or supply them in
msg.payload. - Keep Dry run checked for validation. Uncheck it explicitly in the editor to send real email.
The free plan allows 100 emails per day and restricts recipients to verified account users until a payment method is added. Use a permitted recipient during validation.
Message format
{
"payload": {
"from": "[email protected]",
"to": ["[email protected]"],
"subject": "Order received",
"text": "Thank you for your order.",
"html": "<p>Thank you for your order.</p>"
}
}
subject and at least one of text or html are required. to can be a single address, comma-separated addresses, or an array of addresses. Display-name address syntax is not supported. Payload from and to override node defaults. Only these documented fields are sent to the API. Incoming messages cannot disable dry-run mode or change the endpoint or credentials.
On success the original message is forwarded with msg.mailchannels:
{ "status": "validated", "statusCode": 200, "dryRun": true }
A real send returns accepted, HTTP 202, and dryRun: false. Acceptance does not prove delivery; use MailChannels webhooks for delivery tracking.
Attach a Catch node for failures. Requests time out after 30 seconds and are cancelled on node shutdown. No automatic retries occur. A network failure can leave the delivery outcome unknown, so an unconditional retry can duplicate email. API response bodies and credentials are not logged or returned. Input/output messages still contain your original email content; avoid logging entire messages with private data.
Development
Run npm ci and npm test. Tests load the actual Node-RED runtime and cover flow wiring, password credentials, validation, dry-run/send status handling, input errors, cancellation, and sanitized failures. Ten tests mock HTTP. Nine additional tests use the real fetch implementation and Node-RED runtime against a loopback TLS server, retaining API-hostname verification. They cover 200/202, untrusted CA/wrong hostname, redirects, API errors, post-receipt disconnect, the actual 30-second timeout, and node-unload cancellation. They use synthetic credentials and no real email. The full 19-test suite takes about 31 seconds and requires OpenSSL for temporary fixture certificates. Test-only routing and CA trust use a development Undici dispatcher; production code is unchanged.
Publication requires a public scoped npm package and a separate Flow Library submission. A local package or repository does not establish a live listing.
The development dependency audit currently reports 17 advisories in Node-RED tooling. This package ships no runtime dependencies. The suggested automatic fix downgrades Node-RED; no forced downgrade or unverified dependency override has been applied. Keep the development editor local and review upstream dependency updates before operating a shared test environment.
