The God of Deliveries — High-performance, intelligent delivery orchestrator for email, SMS, push notifications, and webhooks.

Website • Documentation • Getting Started • Contributing

ThorMail is a self-hosted message delivery orchestrator designed to be the intelligent bridge between your application and any delivery provider. Whether you're sending transactional emails, SMS, push notifications, or webhooks, ThorMail routes and manages delivery through your chosen adapters with extreme speed and reliability.

Note: ThorMail does not deliver messages directly to the final recipient. Instead, it routes and manages delivery through your configured adapters (SendGrid, AWS SES, Twilio, SMTP, etc.).

• 🚀 Extreme Speed — Ultra-fast asynchronous API with responses in milliseconds
• ⚡ Automatic Failover — Configure multiple adapters with priority-based routing
• 🔌 Zero Vendor Lock-in — Switch providers instantly, no code changes required
• 🔒 Self-Hosted & Secure — Your data never leaves your infrastructure
• 📦 Multi-Channel — Email, SMS, Push Notifications, Webhooks, and more

This monorepo contains the open-source ecosystem components for ThorMail:

thormail-ecosystem/
├── Adapters/               # Provider adapter packages (NPM modules)
│   └── thormail-adapter-*  # Community & official adapters
├── Clients/                # SDK clients for various platforms
│   ├── js/                 # Official Node.js client (@thormail/client)
│   └── wordpress/          # Official WordPress plugin
├── Dockers/                # Docker images for the ecosystem
│   └── Postgres18/         # PostgreSQL 18 with pg_partman
└── .github/                # Issue templates & security policy

The ThorMail Core (Backend, Worker, and Dashboard) is distributed separately as compiled Docker images and is subject to its own proprietary license. Visit thormail.io for more information.

• Docker Engine 20.10+
• A running ThorMail Core instance (Backend, Worker, Dashboard)

For complete installation instructions, including Core setup, visit the Official Documentation.

npm install @thormail/client

import { ThorMailClient } from '@thormail/client';

const client = new ThorMailClient({
  baseUrl: 'https://api.your-thormail-server.com',
  workspaceId: 'your-workspace-id',
  apiKey: 'your-api-key'
});

// Send an email
const result = await client.send({
  to: 'user@example.com',
  subject: 'Welcome to ThorMail!',
  body: '<h1>Hello {{name}}!</h1>',
  data: { name: 'John' }
});

console.log('Queued with ID:', result.id);

⚠️ Security Warning: The Node.js client is designed for server-side use only. Never expose your API key in client-side code.

Note: "Official" means these adapters are developed and maintained by the ThorMail team. They are not affiliated with or endorsed by the service providers themselves (e.g., OneSignal, SendGrid, etc.).

Service Name	Package	Type	Description	NPM
Mailchimp Transactional	thormail-adapter-mandrill-email	EMAIL	High-volume transactional email delivery platform by Mailchimp.
OneSignal	thormail-adapter-onesignal	EMAIL	Market-leading customer engagement platform for push notifications.
Resend	thormail-adapter-resend	EMAIL	Modern, developer-first email API for building transactional emails.
Amazon SES	thormail-adapter-ses	EMAIL	Scalable, cost-effective, and reliable cloud-based email service.
SMTP	thormail-adapter-smtp	EMAIL	Standard protocol for sending emails via any custom mail server.
Telegram	thormail-adapter-telegram	TELEGRAM	Cloud-based messaging app with an extensive API for bots.
Generic REST	thormail-adapter-generic-rest	REST	Universal adapter to connect with any RESTful API endpoint.

The Type column indicates how ThorMail routes messages to adapters. When you send a message with a specific type (e.g., type: 'TELEGRAM'), ThorMail routes it to all adapters matching that type.

• EMAIL (default): Adapters without an explicit type handle standard email messages.
• Custom types (TELEGRAM, SMS, DISCORD, etc.): Completely open-ended—you invent the type, and messages using it are routed to matching adapters.

You can have multiple adapters of the same type installed simultaneously. ThorMail will distribute load among them based on priority and health status.

📖 Learn more: Creating Adapters - getMetadata()

Package	Platform	NPM
@thormail/client	Node.js
thormail	WordPress	WordPress Plugin

Image	Description	Docker Hub
thormail/postgres-thormail	PostgreSQL 18 + pg_partman

ThorMail's modular adapter system allows you to connect to any provider. Adapters are NPM packages that follow a standardized interface.

thormail-adapter-{provider-name}

// index.js
export default class MyServiceAdapter {
  static getConfigSchema() {
    return [
      { name: 'apiKey', label: 'API Key', type: 'password', required: true },
      { name: 'from_email', label: 'From Email', type: 'text', required: true }
    ];
  }

  static getMetadata() {
    return {
      name: 'My Service',
      description: 'Send messages via MyService API'
    };
  }

  constructor(config) {
    this.config = config;
  }

  async sendMail({ to, subject, body, data }) {
    // Your implementation here
    return { success: true, id: 'message-id' };
  }

  async validateConfig() {
    return { success: true, message: 'Valid!', canValidate: true };
  }

  async healthCheck() {
    return 'HEALTHY';
  }
}

For detailed instructions, see the Official Adapter Documentation.

If you discover a security vulnerability, please do not report it in a public issue.

📧 Email: security@thormail.io

We will acknowledge receipt within 48 hours and follow responsible disclosure practices.

We welcome contributions from the community! Whether you're creating a new adapter, improving documentation, or fixing bugs, your help is appreciated.

1. Discuss First: Open a Discussion before major changes
2. Follow Guidelines: Read our Contributing Guide
3. Test Thoroughly: Ensure your code works in a non-production environment
4. Submit PR: Open a pull request with clear descriptions

Use our Issue Templates:

• 🐛 Adapter Bug — Issues specific to an adapter
• 🔧 Core Issue — Orchestrator logic bugs (include Docker version)
• ✨ Feature Request — New functionality proposals

This repository is licensed under the MIT License.

Important: This license applies exclusively to the open-source adapters, clients, and documentation in this repository. The ThorMail Core (distributed as compiled Docker images) is NOT covered by this license and is subject to its own proprietary End-User License Agreement (EULA).

See LEGAL.md for full legal information and disclaimers.

• 🌐 Website: thormail.io
• 📖 Documentation: docs.thormail.io
• 📧 Security: security@thormail.io

ThorMail: Orchestrating the future, one delivery at a time.