Nostr notes by Armin Reiter (Unofficial)

Test emails locally, mock Resend, SendGrid and SMTP with ...

2026-10-21T03:32:14Z

Test emails locally, mock Resend, SendGrid and SMTP with MailDotNull

Who hasn’t sent a test email to a real customer by accident? Or burned through the free tier of an email provider while testing the signup flow for the 50th time? If you test emails during local development, then you need something that accepts the mails, shows them to you, and delivers nothing. That’s why I built MailDotNull – a local mail catcher and mock email API for Resend, SendGrid, Mailjet, Mailgun, Postmark, Brevo, Amazon SES and plain SMTP.
In this blog post, I’ll show how to run MailDotNull with Docker, how to point the official SDKs at it, and how to use it for error testing and in integration tests. Let’s get started.
What is MailDotNull?
MailDotNull is an open source mail catcher like Mailpit – but it also mocks the HTTP send APIs of the popular email providers. You don’t change your code and you don’t write test doubles. You just change the base URL of the SDK, and every email lands in a live web inbox instead of a real mailbox.
Some facts at a glance:
Mocked providers: Resend, SendGrid, Mailjet, Mailgun, Postmark, Brevo, Amazon SES v2 – and SMTP (plain, STARTTLS and SMTPS)
Provider-faithful responses: each endpoint returns the real success shape (message ids, HTTP 202 + X-Message-Id, …), so the official SDKs treat the send as successful
Any API key works, any SMTP credentials work
In-memory only: no database, no files – a restart clears the inbox (that’s a feature!)
Single Go binary with the web UI embedded, available as Docker image for amd64 and arm64
License: MIT
Why not just use Mailpit?
Mailpit is great, and I used it for years. But it only speaks SMTP. Most of my projects don’t use SMTP anymore – they use the SDK of Resend or SendGrid, which calls an HTTP API. So for local development, I had two options: send real emails to the provider (with a test domain and a test key), or mock the SDK in my code. I didn’t like both.
With MailDotNull, the app uses exactly the same code path as in production – the same SDK, the same request, the same response handling. Only the URL is different. In my opinion, that’s the best way to test emails locally, because you also find bugs in the parts around the send (templates, error handling, retries).
Step 1: Start MailDotNull with Docker
The easiest way is Docker. Use the following command:
docker run -d --name maildotnull \
-p 8025:8025 -p 1025:1025 -p 1587:1587 -p 1465:1465 \
maildotnull/maildotnull
After that, the following ports are available:
http://localhost:8025 – web UI and all provider APIs
localhost:1025 – SMTP (plaintext, no STARTTLS, auth optional)
localhost:1587 – SMTP with STARTTLS
localhost:1465 – SMTPS (implicit TLS)
If you use Podman, then add -e HOSTNAME=0.0.0.0 for the 0.1.0 image – Podman sets HOSTNAME to the container hostname, which the server would otherwise use as bind address:
podman run -d --name maildotnull \
-e HOSTNAME=0.0.0.0 \
-p 8025:8025 -p 1025:1025 -p 1587:1587 -p 1465:1465 \
docker.io/maildotnull/maildotnull
I personally prefer to add it to the docker-compose.yml of the project, so it starts together with the database:
services:
# local mail catcher - nothing is delivered
maildotnull:
image: maildotnull/maildotnull:latest
ports:
- "8025:8025" # web ui + provider apis
- "1025:1025" # smtp
Step 2: Send a test email
Let’s check if it works. The following request uses the Resend API format – the API key can be anything:
curl http://localhost:8025/emails \
-H "Authorization: Bearer re_anything" \
-H "Content-Type: application/json" \
-d '{"from": "Test <test@example.dev>", "to": ["you@example.com"], "subject": "Hello from MailDotNull", "text": "It works!"}'
Open http://localhost:8025 and the mail is already there. The inbox uses server-sent events, so you don’t have to refresh the page.
Step 3: Point your SDK at MailDotNull
Each provider is mocked at the exact path that its SDK calls, so switching is one config line. For Resend, it looks like this:
import { Resend } from "resend";
// in development, send everything to maildotnull instead of resend
const resend = process.env.NODE_ENV === "production"
? new Resend(process.env.RESEND_API_KEY)
: new Resend("re_mock", { baseUrl: "http://localhost:8025"; });
await resend.emails.send({
from: "Armin <hello@example.dev>",
to: ["customer@example.com"],
subject: "Welcome!",
html: "<p>Thanks for signing up.</p>",
});
For the other providers, you have to set the following options:
SendGrid: client.setDefaultRequest(“baseUrl”, “http://localhost:8025“)
Mailjet: new Mailjet({ apiKey, apiSecret, config: { host: “localhost:8025” } })
Mailgun: mailgun.client({ username: “api”, key: “mock”, url: “http://localhost:8025” })
Postmark: new ServerClient(“mock”, { requestHost: “localhost:8025”, useHttps: false })
Brevo: set the base path of the SDK to http://localhost:8025/v3
Amazon SES v2: new SESv2Client({ endpoint: “http://localhost:8025“, credentials: { accessKeyId: “mock”, secretAccessKey: “mock” } })
If your app uses SMTP (e.g. with nodemailer), then use host localhost and port 1025:
import nodemailer from "nodemailer";
// port 1025 never advertises STARTTLS, so no tls config is needed
const transport = nodemailer.createTransport({
host: "localhost",
port: 1025,
});
Note: the certificate on port 1587 and 1465 is self-signed and regenerated on every start. If you want to test TLS, then you have to accept it in your client (e.g. tls: { rejectUnauthorized: false } in nodemailer). Attention! Only do this for MailDotNull, never for a real mail server!
Step 4: Check how the email looks on mobile and in dark mode
This is the part where I spent most of the time, and I really like the result. Every HTML mail renders in a sandboxed iframe, and you have the following tools:
Device widths: desktop, tablet (768px) and mobile (375px)
Dark mode simulation: how Gmail Android, Gmail iOS, Apple Mail, Outlook.com and Yahoo Mail transform your mail in dark mode
HTML Check: flags HTML/CSS features that are known to break in mail clients
Link Check: checks the HTTP status of every link in the mail
Source, Text, Headers and Raw tabs – Raw shows the payload exactly as received
Note: the mail clients don’t publish their dark mode algorithms, so the simulation is an approximation. It’s a very good preview, but not pixel truth.
Step 5: Test error handling – rate limits, server errors, timeouts
What happens in your app if SendGrid returns a 429? Or if the SMTP server doesn’t answer? In my experience, this code path is never tested, because it’s hard to reproduce with a real provider. With MailDotNull, you can make any provider misbehave – via the flask button in the header of the web UI, or via the API:
# sendgrid returns 429, all other providers work normally
curl -X PUT http://localhost:8025/api/error-testing \
-H "Content-Type: application/json" \
-d '{"providers": {"sendgrid": "rate-limit"}}'
The following modes are available:
HTTP providers: off, delay, rate-limit (429), server-error (500), timeout – for all providers at once or per provider
SMTP: off, delay, timeout, reject-temporary (451), reject-permanent (550)
SMTP auth: optional or required – when required, unauthenticated senders get “530 Authentication required”
delaySeconds: how long the delay waits (1-300 seconds, default 10)
The error responses use the real error format of each provider, so the official SDKs throw their typed errors – exactly like in production. To reset everything, use the following command (or just restart the container):
curl -X PUT http://localhost:8025/api/error-testing \
-H "Content-Type: application/json" \
-d '{"http": "off", "providers": {"sendgrid": "inherit"}, "smtp": "off"}'
Use MailDotNull in integration tests and CI
The web UI uses a small API, and you can use it in your tests as well. So you can trigger e.g. a password reset in your app and then check if the mail was sent:
// clear the inbox before the test
await fetch("http://localhost:8025/api/messages";, { method: "DELETE" });
// ... trigger the password reset in your app ...
// check that exactly one mail was sent to the user
const messages = await (await fetch("http://localhost:8025/api/messages";)).json();
const mail = messages.find((m) => m.to.includes("user@example.com"));
expect(mail.subject).toBe("Reset your password");
The list contains a summary of each mail (id, source, from, to, subject, snippet, …). For the full mail incl. HTML body, use GET /api/messages/:id. In a CI pipeline, you start MailDotNull as a service container, and that’s it – no API keys, no test domain, no secrets in the pipeline.
Note: MailDotNull keeps the most recent 1000 messages in memory. For tests, I recommend to clear the inbox before each test, so the tests don’t depend on each other.
Is MailDotNull safe to use?
Nothing is delivered and nothing is persisted – that’s the whole idea. HTML bodies always render in a fully sandboxed iframe, so a caught mail can’t run scripts or touch the app.
But be careful: MailDotNull accepts any API key and any credentials. It’s a tool for local development and CI, so don’t expose it to the internet!
Further Information
MailDotNull on GitHub: https://github.com/maildotnull/maildotnull
MailDotNull on Docker Hub: https://hub.docker.com/r/maildotnull/maildotnull
Mailpit: https://mailpit.axllent.org/
Resend Node.js SDK: https://github.com/resend/resend-node
Nodemailer: https://nodemailer.com/
The post Test emails locally, mock Resend, SendGrid and SMTP with MailDotNull appeared first on arminreiter.com.

https://arminreiter.com/2026/10/test-emails-locally-mock-resend-sendgrid-and-smtp-with-maildotnull/

#smtp #maildotnull #testemails #emailslocally #resend #docker #amazonses #use #sdk #sendgrid

#rss #feeds #linksharing #qwibbit

Alphorn: self-hosted notification router for webhooks Who isn’t ...

2026-10-16T02:56:52Z

Alphorn: self-hosted notification router for webhooks

Who isn’t tired of notifications that are spread over a dozen places? The backup script sends an email, the uptime monitor pings Telegram, the CI pipeline posts to Slack, and the contact form on the website sends… well, nothing, because nobody configured it. That’s why I built Alphorn – a self-hosted notification router that receives a webhook and sends the message to the channels where you actually want it.
In this blog post, I’ll explain what Alphorn is, how it works, and how to send your first notification in a few minutes – hosted on alphorn.dev or self-hosted on your own server. I’ll also show how I use it for backups, scripts and AI agents. Let’s get started.
What is Alphorn?
Alphorn is an open source notification router. You get a webhook URL, every service that can send an HTTP POST request calls that URL, and Alphorn delivers the message to one or multiple channels: Slack, Discord, Microsoft Teams, Telegram, Matrix, Mattermost, email (SMTP, SendGrid, Mailgun), SMS (Twilio, Vonage), push (ntfy, Gotify, Pushover), PagerDuty, Opsgenie, a generic webhook and many more – in total more than 20 channels.
Between the webhook and the channels there are filter rules. They decide which message goes where, e.g. “everything to Slack, but only priority 4 and 5 to Telegram and email”. If a channel is down, then Alphorn retries the delivery automatically, and you can see the full delivery history in the dashboard.
Some facts at a glance:
License: AGPL-3.0-or-later (open source), with a commercial license available
Hosted version: app.alphorn.dev, with a free tier (3,000 messages per month, 3 webhooks, 3 channels)
Self-hosted: Docker Compose, Podman or from source – the only dependency is PostgreSQL 18
Stack: Next.js, PostgreSQL and pg-boss as queue (no Redis, no separate message broker)
Reliability: up to 5 delivery attempts with exponential backoff
No SDK needed: it’s a plain HTTP POST, so curl, Powershell, Python, Go or any monitoring tool works
Why I built a notification router
In my case, the problem was not one big system, but a lot of small ones. Backup jobs, cron jobs, uptime checks, deployments, contact forms, and lately also AI coding agents that run for 20 minutes and then wait for my decision. Every tool has its own way to notify you, and every time I wanted to change something (e.g. move alerts from Telegram to Matrix), I had to touch the tool, the script, or the server again.
So the idea of Alphorn is simple: the sender only knows one URL. Where the message ends up is configured in one place – and if I want to change it, then I change it in Alphorn and not in 15 scripts. Simple and clean!
How does Alphorn work?
The flow has three parts:
Webhooks: the entry point. Each webhook has a unique URL like https://app.alphorn.dev/n/V1StGXR8_Z5jdHi6B-myT and accepts JSON, plain text, or Slack-compatible payloads.
Channels: the destinations – a Slack workspace, a Telegram bot, an SMTP server, a phone number for SMS, and so on.
Filters: rules on the link between a webhook and a channel. You can filter by priority, tags, title, message, or any field of the JSON payload (also with regex).
When a request arrives, Alphorn stores it, answers with “201 Created” immediately, and puts the delivery into a queue. A worker picks up the job and sends it to every channel whose filter matches. That’s why the sender doesn’t have to wait for Slack or Telegram, and a slow channel doesn’t block your script.
Step 1: Choose hosted or self-hosted
You can use Alphorn in two ways:
Hosted: sign up at app.alphorn.dev and you can send your first notification right away. The free tier is enough for most personal setups.
Self-hosted: run it on your own server. All features are available, there are no message limits, and your data stays on your infrastructure.
If you want to self-host it, then the following docker-compose.yml is everything you need:
services:
alphorn:
image: ghcr.io/alphorn-dev/alphorn:latest
ports:
- "3000:3000"
environment:
DATABASE_URL: postgresql://alphorn:secret@db:5432/alphorn
# generate with: openssl rand -base64 32
BETTER_AUTH_SECRET: your-secret-key
# public url of your instance - https in production!
BETTER_AUTH_URL: http://localhost:3000
depends_on:
db:
condition: service_healthy
restart: unless-stopped
db:
image: postgres:18-alpine
environment:
POSTGRES_USER: alphorn
POSTGRES_PASSWORD: secret
POSTGRES_DB: alphorn
volumes:
# postgres 18 stores data under /var/lib/postgresql (not /data anymore)
- pgdata:/var/lib/postgresql
healthcheck:
test: ["CMD-SHELL", "pg_isready -U alphorn"]
interval: 5s
retries: 5
restart: unless-stopped
volumes:
pgdata:
Start it with the following command and open http://localhost:3000 to create your first account:
docker compose up -d
Note: Alphorn needs HTTPS for logins (except on localhost). For production, put it behind a reverse proxy like Caddy, Nginx or Traefik and set BETTER_AUTH_URL to the public https URL.
Attention! PostgreSQL 18 is required – Alphorn uses the built-in uuidv7() function, which doesn’t exist in older versions.
Step 2: Add a channel
After the login, the first thing to configure is a channel:
Navigate to “Channels” and click “Add channel”
Select the type, e.g. “Telegram” or “Slack”
Give it a speaking name, e.g. “telegram-armin” or “slack-alerts”
Enter the credentials of the channel (bot token, webhook URL, SMTP server, …) and save it
I recommend to send a test message directly from the channel page, so you know that the channel works before you connect anything to it.
Step 3: Create a webhook
Next step is to create the webhook:
Navigate to “Webhooks” and click “Create webhook”
Give it a name, e.g. “Server Alerts”
Select the channels it should deliver to
Switch on “API key required” if the sender can send custom headers
Create it and copy the API key – it is shown only once!
Note: by default the webhook URL is the only secret. Services like GitHub, Stripe or many monitoring tools can’t send custom headers, so for them you leave the API key off. For everything else (your own scripts, CI pipelines), I suggest to switch it on.
Step 4: Send your first notification
Now let’s send a message. The easiest way is curl:
curl -X POST https://app.alphorn.dev/n/V1StGXR8_Z5jdHi6B-myT \
-H "Authorization: Bearer $ALPHORN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Server Alert",
"message": "CPU usage above 90% on web-01",
"priority": 4,
"tags": ["infrastructure", "critical"]
}'
Alphorn answers with the message id:
{
"messageId": "0199b2f4-3c1e-7a8d-9f20-5d4c3b2a1e0f"
}
All fields are optional. The priority goes from 1 (lowest) to 5 (urgent), tags are used for filtering, and you can attach any JSON data you want – Alphorn keeps the whole body and you can filter on it later. If your tool sends different field names (e.g. “subject” or “text”), then Alphorn tries to guess them, or you map them with webhook templates.
The same request in Powershell, because I use it a lot on Windows servers:
# send a notification to alphorn from powershell
$body = @{
title = "Disk space low on $env:COMPUTERNAME"
message = "Drive C: has less than 10% free space"
priority = 4
tags = @("windows", "disk")
} | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri $env:ALPHORN_WEBHOOK_URL `
-Headers @{ Authorization = "Bearer $env:ALPHORN_API_KEY" } `
-ContentType "application/json" -Body $body
Step 5: Route notifications with filters
This is the part I personally like most. Filters are set per channel on a webhook, so one webhook can deliver to multiple channels with different rules. A typical setup looks like this:
Slack (#alerts): no filter – receives everything, so the team has the full picture
Email: priority greater than 3 – only priority 4 and 5
Telegram: priority greater than 3 – only priority 4 and 5, so I get it on my phone
A message with priority 2 goes to Slack only. A message with priority 5 goes to Slack, email, and Telegram. You can combine conditions with AND (within a group) and OR (multiple groups), e.g. “priority greater than 4 AND tag production” OR “tag security”.
You can also filter on the payload. If your JSON contains {“payload”: {“environment”: “production”}}, then the path “payload.environment” equals “production” can route production deployments to PagerDuty, while staging only goes to Slack.
Note: each filtered channel has a “Test filter” button. Use it! You can enter a sample message and see which conditions match – before the real alert at 3 am shows you that the filter was wrong.
How I use Alphorn – a few real examples
The following examples are the setups I use or see most often.
Backup failed – send a notification only if the backup script returns an error. Plain text is enough here, and the headers set title, priority and tags:
#!/usr/bin/env bash
# nightly backup - notify alphorn only if it fails
if ! /usr/local/bin/backup.sh; then
curl -fsS -X POST "$ALPHORN_WEBHOOK_URL" \
-H "Authorization: Bearer $ALPHORN_API_KEY" \
-H "Content-Type: text/plain" \
-H "X-Title: Backup failed on $(hostname)" \
-H "X-Priority: 4" \
-H "X-Tags: backup,failed" \
-d "Nightly backup failed - please check the logs"
fi
Other use cases where it works really well:
Uptime monitoring: the monitor calls the webhook, and the alert goes to Teams and Telegram at the same time
GitHub webhooks: new release or failed workflow – Alphorn has presets for common sources, so you don’t have to map the fields yourself
Contact forms: the website calls the webhook, the message arrives via email and in a Slack channel
Cron jobs and CI/CD pipelines: one curl line at the end of the job
Get notified by AI agents (Claude Code, Codex, Cursor)
A use case I didn’t expect at the beginning, but use every day now: AI coding agents. They work on a task for a while and then wait for a permission or a decision – and if you don’t look at the terminal, then they wait forever.
For that, I built an MCP server for Alphorn. It gives the agent a “send_notification” tool, so it can tell you when it’s finished, failed, or needs your input. For Claude Code, it’s one command:
claude mcp add alphorn -s user \
-e ALPHORN_WEBHOOK_URL=https://app.alphorn.dev/n/V1StGXR8_Z5jdHi6B-myT \
-e ALPHORN_API_KEY=alp_... \
-- npx -y @alphorn/mcp
It also works with Claude Desktop, Cursor, OpenAI Codex and any other MCP client. If you prefer no MCP server at all, then the docs also have ready-to-use Claude Code hooks (Stop and Notification events) that call the webhook with curl. In combination with a filter like “priority greater than 3 to SMS”, I only get a text message when the agent is really blocked. That’s awesome.
How is Alphorn different from ntfy, Apprise or Gotify?
I get this question a lot, and it’s a fair one. ntfy, Gotify and Apprise are great tools, and Alphorn even supports ntfy and Gotify as channels. But they focus on sending a message to a destination. Alphorn is a routing layer on top: one incoming webhook, filter rules, and fan-out to multiple channels – plus a web dashboard, delivery history, retries, and organizations with roles for teams.
On the other side, Alphorn is not a product notification platform like Novu, Knock or Courier. It’s not built to send onboarding emails to millions of end users. It’s built for developers and ops teams who want their technical notifications in the right place. Is it the right tool for every case? No, it is not – but for “my systems need to tell me something”, it’s exactly what I wanted.
Is Alphorn free?
Yes. The source code is on GitHub under AGPL-3.0-or-later, and you can self-host it for free without feature restrictions – personal, internal, or commercial. If you run a modified version as a public network service, then you have to publish your changes (that’s how AGPL works). For companies that can’t comply with the AGPL, there is a commercial license.
If you don’t want to run it yourself, then the hosted version at app.alphorn.dev has a free tier with 3,000 messages per month. Each accepted webhook request counts as one message, no matter to how many channels it is delivered.
What happens when a channel is down?
Alphorn makes up to 5 delivery attempts with exponential backoff, starting at around 30 seconds – all attempts are done within roughly 15 minutes. Permanent errors (e.g. a wrong token) are not retried, because retrying wouldn’t help anyway. If all attempts fail, then the delivery is marked as failed, and you can configure a failure notification via a backup channel. So if Slack is down, then you still get the message on Telegram.
I’m working on more channels and integrations – so stay tuned!
Further Information
Alphorn website: https://alphorn.dev
Alphorn hosted app: https://app.alphorn.dev
Documentation: https://docs.alphorn.dev
Self-hosting guide: https://docs.alphorn.dev/self-hosting/
Filtering rules: https://docs.alphorn.dev/filtering/
API reference: https://docs.alphorn.dev/api-reference/
Claude Code notifications: https://docs.alphorn.dev/ai-agents/claude-code/
Source code (GitHub): https://github.com/alphorn-dev/alphorn
MCP server (GitHub): https://github.com/alphorn-dev/mcp
The post Alphorn: self-hosted notification router for webhooks appeared first on arminreiter.com.

https://arminreiter.com/2026/10/alphorn-self-hosted-notification-router-for-webhooks/