---
title: "Deploy MailChannels Email API: Node.js Transactional Email Starter"
description: "Send receipts, resets and alerts from Node.js with MailChannels."
category: "Starters"
url: https://railway.com/deploy/mailchannels-email-api
---

# Deploy MailChannels Email API: Node.js Transactional Email Starter

Send receipts, resets and alerts from Node.js with MailChannels.

**[Deploy MailChannels Email API: Node.js Transactional Email Starter on Railway](https://railway.com/template/mailchannels-email-api)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/mailchannels-email-api/manifest.json

- **Creator:** blueorange
- **Category:** Starters

## Template content

### MailChannels Starter

- **Source:** mailchannels/mailchannels-node-railway-starter
- **Start command:** `pnpm start`
- **Health check:** /health
- **Public domain:** Yes

## Documentation

# Deploy and Host MailChannels Email API Starter on Railway

![MailChannels logo](https://ph-files.imgix.net/e25cf7a1-6792-4210-8e27-214d7471cf26.png)

MailChannels is an email delivery service for developers. Its **Email API** sends transactional email such as receipts, password resets, sign-in codes and account alerts over a REST API or SMTP, with official SDKs, DKIM signing, domain lockdown and signed delivery webhooks. This template deploys a small **Node.js starter service** that sends email through the MailChannels Email API using the official `@mailchannels/sdk` package, so you have a working base to build your own email service on Railway. The starter is MIT licensed and comes from MailChannels' own starter repository. MailChannels' free developer plan sends up to 100 emails a day, with paid plans priced by volume. Resend's Pro plan costs $20 per month for 50,000 emails. The service itself costs only a few dollars a month on Railway.

---

## What This Template Deploys

| Service | Purpose |
|---|---|
| **MailChannels Starter** | A Node.js 22 service built from `mailchannels/mailchannels-node-railway-starter`, started with `pnpm start`, on port `8080` with a public domain. Exposes `POST /api/send` and a health check at `/health`. |

There is no database or volume. All email delivery, retries and bounce handling happen on MailChannels' side.

---

## Important: This Is a Starter, Not a Finished Mail Service

The sample `POST /api/send` route sends a fixed test message from `acme@example.com` to `to@example.net`, and it has **no authentication**. As deployed, sends will fail because MailChannels only accepts mail from domains you have authorized, and anyone who finds the URL could call the route.

**Before real use:** fork the starter repository, change the sender to an address on your own domain, accept recipients and content from your app, and protect the route with an API key or call it only over Railway's private network. Then point the service at your fork.

---

## About Hosting a MailChannels Email Service

Most apps need to send email, but running a mail server means managing IP reputation, bounces, blocklists and authentication records. An email API moves that work to a provider. A small service on Railway that wraps the API gives your other services one place to send email from, with your API key kept out of front-end code.

**REST and SMTP.** Send through the REST API with the SDK, or use SMTP from apps that only speak SMTP.

**Domain lockdown.** MailChannels only sends for domains you authorize with a DNS record, which stops anyone else from using your account to send as your domain.

**DKIM, SPF and DMARC.** Sign messages with DKIM and publish SPF and DMARC records so inbox providers trust your mail.

**Delivery webhooks.** Receive signed webhooks for delivered, bounced, complained and other events, and update your app accordingly.

**Sub-accounts.** Separate sending for different customers or products with sub-accounts, each with its own keys and limits.

**Official SDK.** The `@mailchannels/sdk` package handles requests, errors and types for TypeScript and JavaScript.

---

## Deploy the Starter in Under 5 Minutes

1. Create a MailChannels account and an API key with the `api` scope in the MailChannels dashboard.
2. Click **Deploy on Railway** and paste the key into `MAILCHANNELS_API_KEY`.
3. Add a Domain Lockdown DNS record for your sending domain, plus SPF, DKIM and DMARC records.
4. Fork the starter, set the sender and recipients in `index.ts` to real addresses, and protect `/api/send`.
5. Point the Railway service at your fork, redeploy, and call `POST /api/send` from your app.

---

## Common Use Cases

- **Receipts and order updates:** confirm purchases, shipping and delivery.
- **Authentication emails:** send password resets, verification links and sign-in codes.
- **Account and security alerts:** notify users about new sign-ins and setting changes.
- **Invitations:** invite people to a workspace, team or project.
- **Billing emails:** send invoices, renewal notices and payment reminders.
- **Welcome series:** greet new users after registration.
- **Service notices:** announce maintenance windows and incidents.
- **Central mail service:** give every service in your Railway project one internal endpoint for sending email.

---

## Configuration

| Variable | Required | Default | Description |
|---|---|---|---|
| `MAILCHANNELS_API_KEY` | Required | you enter it | MailChannels API key with the `api` scope |
| `PORT` | Auto-set | `8080` | Port the Node.js server listens on |

**Sender domain.** Use a `from` address on a domain you control and have authorized with Domain Lockdown. Messages from unauthorized domains are rejected.

**DNS records.** Add an SPF record that includes MailChannels, a DKIM key for signing, and a DMARC policy. Good authentication is the biggest factor in reaching the inbox.

**Protecting the endpoint.** Add a shared secret header check to `/api/send`, or remove the public domain and call the service from other Railway services over the private network. Note that the starter listens on `0.0.0.0`; to reach it over Railway's IPv6 private network, change it to listen on `::`.

**Templates and content.** Pass subject, HTML and text from your app, or render templates in the service with a library of your choice.

**Webhooks.** Add a route that receives MailChannels delivery webhooks and verifies their signatures before trusting them.

**Usage limits.** The free plan stops sending after its daily limit until the next day, so move to a paid plan before launch traffic.

**Error handling.** The SDK returns an error object with a status code instead of throwing. Log it, return a clear response to the caller, and retry only on temporary failures so users never receive duplicates.

**Logs.** The service logs failed sends to standard output, so errors show in the Railway logs for the service.

---

## Extending the Starter

**Accept a request body.** Read JSON from the request with `to`, `subject`, `text` and `html`, validate the addresses, and pass them to `mailchannels.emails.send`.

**Add authentication.** Compare a header such as `x-api-key` with a secret stored in a Railway variable and reject requests that do not match.

**Queue large batches.** For newsletters or bulk notices, put messages on a queue and send them at a steady rate instead of all at once.

**Handle webhooks.** Add a `/webhooks/mailchannels` route, verify the signature on each event, and mark bounced or complaining addresses so you stop mailing them.

**Use templates.** Keep email templates in the repository and render them with your preferred templating library before sending.

---

## MailChannels vs. Alternatives

| Feature | MailChannels Email API | Resend | Postmark | Amazon SES |
|---|---|---|---|---|
| Hosting | Hosted API | Hosted API | Hosted API | Hosted API |
| License | Proprietary service, MIT starter | Proprietary | Proprietary | Proprietary |
| REST API and SMTP | ✅ | ✅ | ✅ | ✅ |
| Free tier | 100 emails/day | Limited free plan | Developer trial | Limited free tier |
| Domain lockdown | ✅ | ❌ | ❌ | ❌ |
| Sub-accounts | ✅ | ❌ | Servers | Configuration sets |
| Price | Free, then volume-based | $20/month for 50,000 | From $15/month for 10,000 | About $0.10 per 1,000 |

Resend is known for its developer experience. Postmark focuses on fast transactional delivery. Amazon SES is the cheapest at scale but needs more setup. MailChannels stands out for domain lockdown and multi-tenant sub-accounts.

---

## Dependencies for MailChannels Starter Hosting

- A Railway account.
- A MailChannels account and API key.
- A domain you control for sending, with DNS access.

### Deployment Dependencies

- [MailChannels starter on GitHub](https://github.com/mailchannels/mailchannels-node-railway-starter): the source deployed here
- [MailChannels Email API docs](https://docs.mailchannels.com/email-api): API, domain lockdown and webhooks
- [@mailchannels/sdk on npm](https://www.npmjs.com/package/@mailchannels/sdk): the official SDK

### Implementation Details

The service uses Node.js's built-in HTTP server with no framework. The SDK dependency follows its latest release on each build. This is a community-listed template based on MailChannels' official starter; MailChannels is a trademark of its owner.

---

## Frequently Asked Questions

**What does this template deploy?**
A small Node.js service that sends email through the MailChannels Email API with the official SDK.

**How much does it cost?**
A few dollars a month on Railway for the service, plus MailChannels usage. MailChannels' free plan sends up to 100 emails a day.

**Why does my first send fail?**
The sample sends from `acme@example.com`. Change the sender to your own authorized domain and set up Domain Lockdown.

**Is the send endpoint safe to expose?**
Not as shipped. Add authentication to `/api/send` or call it only over Railway's private network.

**Can I use SMTP instead?**
Yes. MailChannels also accepts SMTP, so apps that only speak SMTP can send without this service.

**How do I track bounces?**
Subscribe to MailChannels delivery webhooks and add a route that verifies and stores the events.

---

## Why Deploy and Host MailChannels Email API Starter on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying the MailChannels Email API starter on Railway, you get a ready base for a transactional email service that keeps your API key server-side and sends through a dedicated delivery provider.


## Similar templates

- [Openfront Gym](https://railway.com/deploy/openfront-gym) — Opensource Mindbody alternative based on Next.js and Keystone.js
- [open-excalidraw](https://railway.com/deploy/open-excalidraw) — Self-hostable collaborative drawing built on Excalidraw
- [Next.js + Prisma + PostgreSQL Starter](https://railway.com/deploy/nextjs-prisma-postgres) — Deploy a Next.js app with Prisma ORM and PostgreSQL in one click.

Open this page in a browser: https://railway.com/deploy/mailchannels-email-api
