Hermes is an open-source, multi-tenant transactional email gateway designed to centralize delivery, template management, and access control. To prevent SMTP network latency (often 500ms to 2s per handshake) and third-party throttling from blocking upstream callers, the system strictly separates HTTP request intake from email execution using an asynchronous BullMQ/Redis queue. Sensitive data is protected using two distinct cryptographic models: stored SMTP credentials and OAuth tokens are encrypted at rest using AES-256-GCM, while programmatic API keys are validated using Argon2id with indexed prefix lookups.

The project is structured as an ecosystem consisting of a REST API gateway, background workers, an administrative dashboard, and a client SDK:

• API Gateway & Workers: github.com/RuanLopes1350/hermes-api

• Admin Dashboard: github.com/RuanLopes1350/hermes-front

• TypeScript Client SDK: github.com/RuanLopes1350/hermes-client

• NPM Package: @ruanlopes1350/hermes-client

1. Problem Statement and Architectural Motivation

In monolithic architectures or microservice networks without a dedicated gateway, handling transactional emails presents three recurring technical issues:

1. HTTP Blocking & Latency Spikes: Connecting directly to an SMTP server (e.g., via Nodemailer in Express or NestJS) during a user sign-up or password reset forces the HTTP thread to wait for DNS resolution, TLS handshakes, and SMTP RCPT TO/DATA acknowledgments before responding to the user.

2. Failure Handling and Retries: If an SMTP server experiences transient network timeouts, services without persistent queues either drop the email or require complex local retry logic that can trigger duplicate dispatches or database locking.

3. Key and Credential Management: Rotating SMTP credentials or granting sending permissions across multiple distinct services creates configuration drift. If an integration API key leaks, revoking it manually across multiple deployment environments causes unexpected downtime.

Hermes addresses these issues by acting as an intermediary service with logical tenant isolation, asynchronous worker execution, and automated cryptographic key rotation.

┌─────────────────────────────────────────────────────────────┐
│           CLIENT SERVICES (@ruanlopes1350/hermes-client)    │
└──────────────────────────────┬──────────────────────────────┘
   (POST /api/emails + X-API-Key)│       ▲ (HMAC Signed Webhook
                                 │       │  for Key Rotation)
                                 ▼       │
┌────────────────────────────────────────┴────────────────────┐
│                    HERMES REST API                          │
│        (Express + Better Auth + Drizzle ORM)                │
└──────────────┬──────────────────────────────┬───────────────┘
               │                              │
(Insert Email record as 'pending')            │ (Enqueue BullMQ Job)
               ▼                              ▼
┌──────────────────────────────┐ ┌────────────────────────────┐
│         POSTGRESQL           │ │        REDIS STORE         │
│  (Tenancy, Keys, Templates)  │ │ (Queues, PubSub, SSE Rate) │
└──────────────────────────────┘ └─────────────┬──────────────┘
                                               │
                                               ▼
                                 ┌────────────────────────────┐
                                 │       HERMES WORKER        │
                                 │   (Nodemailer / OAuth2)    │
                                 └─────────────┬──────────────┘
                                               │
                                               ▼ (TLS / SMTP)
                                 ┌────────────────────────────┐
                                 │        SMTP SERVERS        │
                                 │    (Gmail, Custom SMTP)    │
                                 └────────────────────────────┘

2. Decoupling HTTP Requests from Email Delivery

The system runs as separate Node.js processes:

The API Gateway (server.ts)

The API accepts incoming requests, performs input validation, authenticates the client via API Key or session cookie, records the message in PostgreSQL with a pending status, and pushes the job payload onto a BullMQ Redis queue. Once the job is pushed, the API immediately responds with a 201 Created status code and the unique email record identifier.

Average API latency remains under 25ms, independent of whether the underlying SMTP server takes 200ms or 4000ms to respond.

The Background Worker (worker.ts)

The worker process listens to the queue, fetches the email payload, and resolves the required credential. It handles:

• Decrypting the SMTP password or generating fresh access tokens via Google OAuth2 (Gmail API).

• Fetching and compiling the MJML template with dynamic Handlebars variables.

• Dispatching the email via Nodemailer.

• Updating the status in PostgreSQL (sent or failed) with execution metadata, logs, and error stacks.

• Emitting Redis Pub/Sub events that feed Server-Sent Events (SSE) on the frontend for live monitoring.

If the delivery fails due to network instability, BullMQ manages exponential backoff retries without blocking new incoming requests.

3. Cryptographic Implementation

Security requirements for a shared gateway require safeguarding credentials at rest and validating high-frequency API calls securely.

3.1 API Keys: Prefix Indexing + Argon2id

Traditional API key storage often uses SHA-256 (vulnerable to fast offline dictionary attacks if leaked) or standard bcrypt (which is compute-heavy when verifying every single HTTP request).

Hermes uses a structured key format:

hm_b5c92a10.e4d3c2b1a0f9e8d7c6b5a4938271605f4581902...
└───┬──────┘ └───────────────────┬───────────────────┘
    │                            └─ 64-char Hex Secret (Argon2id hashed)
    └─ 8-char Hex Prefix (Indexed plain-text)

Verification Flow:

1. The request provides the header X-API-Key: hm_<prefix>.<secret>.

2. The middleware parses the prefix (hm_b5c92a10) and queries the database:

   SELECT * FROM credential WHERE prefix = 'hm_b5c92a10' AND is_active = true;
   

   This keeps database lookup at O(1)O(1) complexity via an indexed column, avoiding full-table scans.

3. Once the single matching record is retrieved, the secret is checked using argon2.verify(key_hash, secret).

4. Argon2id provides memory-hard resistance against GPU-accelerated brute force without incurring the penalty of hashing against every record in the table.

3.2 Sensitive Credentials at Rest: AES-256-GCM

SMTP passwords and OAuth2 refresh tokens are stored in the database as encrypted strings formatted as:

<iv_hex>:<auth_tag_hex>:<ciphertext_hex>

• Algorithm: aes-256-gcm (Galois/Counter Mode).

• IV: 16-byte initialization vector generated randomly for each encryption operation.

• Authentication Tag: 16-byte tag used to detect ciphertext tampering or corruption prior to decryption.

• Master Key (MASTER_KEY): Provided via environment variables, never committed or exposed over the API.

4. Zero-Downtime Automated Key Rotation

API keys should rotate periodically, but updating keys in production often leads to service interruptions if the client application is not updated in sync.

Hermes handles rotation via an asynchronous scheduled process:

1. Daily Cron Job (system.ts): BullMQ runs a daily check (0 0 * * *) searching for active credentials approaching their expiration date (rotate_threshold_days).

2. Webhook-First Strategy: When a key is marked for rotation, the system generates the new key and immediately sends an HTTP POST request to the service's configured webhook URL.

3. HMAC SHA-256 Signature: To prevent webhook spoofing, payloads are signed with an X-Hermes-Signature header calculated using the service's private webhook secret:

   const signature = crypto
     .createHmac('sha256', webhookSecret)
     .update(JSON.stringify(payload))
     .digest('hex');
   

4. Guaranteed Delivery: If the client application's webhook returns an error (or times out), the key rotation is aborted, the database is not updated, and BullMQ schedules a retry. The active key continues to work.

5. Database Commit: Only when the client's webhook responds with 200 OK does Hermes update the hash and expiration date in the database.

5. Ecosystem Components

5.1 The Admin Dashboard (hermes-front)

Built with Next.js (App Router), Tailwind CSS, and Shadcn UI:

• Tenancy Management: Create isolated services, add team members with role-based permissions (admin, member), and manage sending quotas.

• Credential Storage: Configure standard SMTP servers or authorize Gmail via Google OAuth2 with automatic token refresh.

• MJML Editor: Integrated Monaco Editor with real-time compilation preview and Handlebars syntax highlighting.

• Live Monitoring: Real-time throughput metrics, queue status, and email delivery states driven by Server-Sent Events (SSE).

5.2 The Client SDK (@ruanlopes1350/hermes-client)

Published to NPM as a lightweight TypeScript client designed for integration:

• Fluent Builder: Construct dispatches with chaining (.to(), .subject(), .useTemplate(), .send()).

• Framework Middleware: Built-in webhook handlers for Express, Fastify, and Next.js that verify signatures and apply new keys in memory or .env automatically.

• Storage Adapters: Decoupled storage interfaces (MemoryAdapter, EnvAdapter, or custom implementations for Redis/DynamoDB).

• Resilience: Automatic retries with jitter and exponential backoff for transient HTTP errors (408, 429, 5xx).

import { HermesClient, MemoryAdapter } from '@ruanlopes1350/hermes-client';

const hermes = new HermesClient({
  baseUrl: 'https://hermes.internal.domain',
  storageAdapter: new MemoryAdapter(process.env.HERMES_API_KEY!),
});

await hermes.email()
  .to('engineer@company.com')
  .subject('Weekly Digest')
  .useTemplate('cltmpl_engineering_digest', { name: 'Alex' })
  .send();

6. Technical Tradeoffs and Limitations

No architecture is without tradeoffs. Building Hermes revealed several constraints that should be evaluated before deploying:

1. Operational Footprint vs. SaaS: Running Hermes requires managing a Node.js runtime, PostgreSQL, Redis, and a background worker container. For small projects that send fewer than 50 emails a day, using a managed API (such as Resend or Postmark) has lower maintenance overhead. Hermes is suited for organizations needing internal data residency, multi-service governance, and private SMTP infrastructure.

2. Argon2id CPU Overhead: While prefix indexing limits lookups to O(1)O(1), Argon2id verification is deliberately CPU-intensive to resist brute-forcing. Under heavy traffic spikes (>500 requests/sec directly on the API), CPU utilization on the API container rises significantly. For extreme throughput, request-rate caching or offloading verification to an edge reverse-proxy may be necessary.

3. Docker Compose Auto-Scaler Constraints: The included worker scaling script (scaler.ts) evaluates Redis queue depth and adjusts Worker replica counts by communicating with the local Docker daemon socket. While sufficient for single-host VPS deployments, this model does not natively orchestrate across distributed clusters (e.g., Kubernetes HPA or Nomad).

4. Deliverability Responsibility: Hermes handles routing, queuing, formatting, and retries. However, it does not replace email deliverability fundamentals. SPF, DKIM, DMARC records, and IP reputation must still be configured on the destination SMTP server or upstream relay provider.

7. Conclusion

By separating API ingestion from transport execution and applying modern cryptography to key management, Hermes provides a structured pattern for transactional email routing in self-hosted environments.

All components of the project are open-source:

• Review the source code and documentation: hermes-api

• Explore the frontend: hermes-front

• Inspect the client library: hermes-client on GitHub and NPM.