Mailmask
Turn Mailmask refusal and test events into ntfy notifications that retain the routing details needed to investigate an alert.
Input Handling
The interpreter reads the versioned JSON payload that Mailmask posts through its ntfy-reverse-proxy notifier. Every field below is required, and fields that aren't listed are ignored.
| Field | Type | Description |
|---|---|---|
version | 1 | Payload format. Any other version fails. |
app | mailmask | App discriminator. Any other app fails with an interpreter hint. |
event | string | Either message-refused for a refusal or test for a CLI test. |
title | string | Notification title supplied by Mailmask. |
message | string | Human-readable refusal or test message. |
priority | 1-5 | Priority level (1 = min, 3 = default, 5 = max). |
tags | string[] | ntfy tags: email for refusals and email, test for CLI tests. |
occurredAt | string | When Mailmask created the notification. |
details | object | Stable routing details described below. |
The details object has these required string fields:
| Field | Description |
|---|---|
alias | Resolved alias address without a subaddress tag. |
envelopeSender | SMTP envelope sender checked by Mailmask's sender rules. |
recipient | Original SMTP envelope recipient, including a subaddress tag when present. |
reason | Stable refusal reason code or test; unknown version 1 codes are retained. |
The notification uses title, message, priority, and tags, then adds alias, envelopeSender, and reason to the body. The event and occurredAt fields are validated but don't appear in the notification.
Supported Events
Mailmask sends these two events:
| Title | Event Key | Priority | Tags |
|---|---|---|---|
| Mailmask refused a message | message-refused | 3 (default) | email |
| Mailmask test notification | test | 3 (default) | email, test |
Refusal reasons are disabled, expired, filtered, misconfigured, and the forward-compatible fallback refused. A CLI test uses test.
Context Setup
- Add an HTTP context — Run
nrp, choose Manage Contexts > Add, pick HTTP, and choose Mailmask as the Interpreter. Answer no to Use session tokens?, because Mailmask sends a fixed token and can't request session tokens. - Deploy — Choose Deploy, then copy the context's URL and token from the Context reference list it prints.
- Add a Mailmask notifier — Run
mm notifier add-reverse-proxy, passing the context URL and its token when authentication is enabled. - Send a test — Run
mm notifier test reverse-proxy, and check that[Mailmask] Mailmask test notificationarrives on the context's topic.
mm notifier add-reverse-proxy reverse-proxy \
--url https://mailmask-example.ntfy.example.com \
--token replace_with_auth_token
mm notifier test reverse-proxy
Set the context's interpreter to mailmask:
{
"id": "mailmask-example",
"name": "Mailmask",
"type": "http",
"interpreter": "mailmask",
"topic": "mailmask",
"mode": "send-once",
"show_visitor_info": false,
"primary_server": "primary",
"servers": ["primary"],
"token": "replace_with_auth_token"
}
With this context, Mailmask posts its notifications to https://mailmask-example.ntfy.example.com with optional bearer authentication.
Notification Output
- Title:
[Mailmask]and the payload'stitle(for example,[Mailmask] Mailmask refused a message). - Body: The payload's
message, a blank line, and the alias, envelope sender, and reason. HTML tags are removed as for every interpreter (see HTML Stripping). - Priority: The payload's
priority, unchanged. Mailmask sends3. - Tags:
mailmaskfirst, then the payload's tags (mailmask,emailfor a refusal).
The interpreter sets no icon, actions, or Markdown, and it doesn't add occurredAt to the body.
Example
Mailmask posts this payload when an expired alias refuses a message:
{
"version": 1,
"app": "mailmask",
"event": "message-refused",
"title": "Mailmask refused a message",
"message": "Mail to old@example.com from sender@shop.test was rejected: Address has expired.",
"priority": 3,
"tags": ["email"],
"occurredAt": "2026-11-05T12:00:00.000Z",
"details": {
"alias": "old@example.com",
"envelopeSender": "sender@shop.test",
"recipient": "old@example.com",
"reason": "expired"
}
}
The proxy publishes it to ntfy with these ntfy headers and body:
X-Title: [Mailmask] Mailmask refused a message
X-Priority: 3
X-Tags: mailmask,email
Mail to old@example.com from sender@shop.test was rejected: Address has expired.
Alias: old@example.com
Envelope sender: sender@shop.test
Reason: expired
ntfy shows the email tag as an emoji and lists mailmask below the notification.
Wrong App Error
A context reads alerts from one app, so a payload whose app names a different supported app fails with HTTP 422 and identifies the correct interpreter:
{
"status": "error",
"message": "This context reads Mailmask alerts, but the payload came from outpost. Set the context's interpreter to outpost."
}
A non-empty body that isn't JSON, JSON missing required fields, an unsupported event, or a version other than 1 also fails with HTTP 422.
tip
For notifier setup, delivery behavior, and the authoritative payload contract, see Refusal Notifications in the Mailmask docs.