CourierX Logo
CourierX Docs
GitHub
Documentation

CourierX Docs

One API. Multiple email providers. Automatic failover + suppressions.

View on GitHub

Overview

CourierX is an open-source email routing service that provides a unified API for multiple email providers with automatic failover, intelligent routing, and built-in suppressions.

What is CourierX?

CourierX eliminates vendor lock-in by providing a single API that works with multiple email providers. When one provider fails, CourierX automatically routes your emails through backup providers.

🔄 Auto Failover

Automatic switching between providers when issues occur

🚫 Suppressions

Built-in bounce and complaint handling

📊 Analytics

Detailed delivery metrics and insights

Quickstart

Get running in under 5 minutes with Docker Compose:

# Clone and start
git clone https://github.com/courierx/courierx
cd courierx
docker-compose up -d

# Send your first email
curl -X POST http://localhost:3000/v1/send \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "from": "hello@yourapp.com",
    "subject": "Hello World",
    "html": "<h1>It works!</h1>"
  }'

Getting Started

Multiple ways to install and deploy CourierX for your needs.

Installation

📦 NPM Package

npm i @courierx/client

🐳 Docker Compose

docker-compose up -d

🔧 From Source

git clone + pnpm dev

Configuration

Set up your environment variables and provider credentials:

# .env
DATABASE_URL="postgresql://..."
SENDGRID_API_KEY="SG.xxx"
AWS_ACCESS_KEY_ID="AKIA..."
AWS_SECRET_ACCESS_KEY="xxx"
MAILGUN_API_KEY="key-xxx"
MAILGUN_DOMAIN="mg.yourapp.com"

Deploy Options

☁️ Cloud Platforms

  • • Render / Railway / Fly.io templates
  • • Supabase / Neon for database

🏠 Self-Host

  • • VPS with Docker + Caddy
  • • Automatic TLS certificates

Guides

Step-by-step guides for common integration patterns and advanced features.

Sending Your First Email

Complete examples with curl, Node.js, and Python

  • • Basic setup
  • • Authentication
  • • Error handling
Read Guide

Adding Providers

Configure SendGrid, SES, Mailgun, and SMTP

  • • API keys
  • • Domain verification
  • • Testing
Read Guide

Webhook Setup

Handle delivery events and bounces

  • • Endpoint configuration
  • • Signature verification
  • • Event processing
Read Guide

Rate Limiting & Warmup

Manage sending limits and domain reputation

  • • Hourly caps
  • • Warmup strategy
  • • Monitoring
Read Guide

n8n Integrations

Workflow automation with visual editor

  • • Retry flows
  • • Warmup automation
  • • Event triggers
Read Guide

Next.js Integration

Complete setup for React applications

  • • API routes
  • • Form handling
  • • TypeScript
Read Guide

API Reference

Complete reference for CourierX API endpoints with request/response schemas.

Authentication

All API requests require authentication via API key or HMAC signature.

# API Key (Header)
Authorization: Bearer your-api-key

# HMAC Signature (Optional)
X-Signature: sha256=computed-signature
X-Timestamp: 1640995200

POST /v1/send

POST/v1/send
{
  "to": "user@example.com",
  "from": "noreply@yourapp.com", 
  "subject": "Welcome!",
  "html": "<h1>Hello World</h1>",
  "text": "Hello World",
  "attachments": [
    {
      "filename": "invoice.pdf",
      "content": "base64-content",
      "contentType": "application/pdf"
    }
  ],
  "tags": ["welcome", "onboarding"],
  "metadata": {
    "userId": "123",
    "campaign": "welcome-series"
  }
}

POST /v1/webhooks/:provider

Receive delivery events from email providers.

{
  "messageId": "msg_123456",
  "event": "delivered",
  "timestamp": "2024-01-15T10:30:00Z",
  "provider": "sendgrid",
  "recipient": "user@example.com",
  "metadata": {
    "userId": "123",
    "campaign": "welcome-series"
  }
}

GET /v1/health

GET/v1/health
{
  "status": "healthy",
  "version": "1.0.0",
  "providers": {
    "sendgrid": "connected",
    "ses": "connected", 
    "mailgun": "error"
  },
  "database": "connected"
}

Examples

Real-world examples and integration patterns for common use cases.

Next.js Integration

TypeScript

Complete setup with API routes and React components

View Example

Express.js Middleware

JavaScript

Email service middleware for Express applications

View Example

Webhook Handling

Node.js

Process delivery events and update your database

View Example

Template Engine

HTML

Dynamic email templates with Handlebars

View Example

Deployment

Deploy CourierX on various platforms for scalability and reliability.

Cloud Deployment

Deploy CourierX on cloud platforms for easy management and scaling:

  • • Render
  • • Railway
  • • Fly.io

Self-Host Deployment

Deploy CourierX on your own infrastructure for full control:

  • • VPS with Docker + Caddy
  • • Automatic TLS certificates

Contributing

Contribute to the development of CourierX and help improve the service.

How to Contribute

Follow these steps to contribute to CourierX:

  • • Fork the repository
  • • Create a new branch
  • • Make your changes
  • • Submit a pull request

Code of Conduct

Please review our code of conduct before contributing:

Code of Conduct