Skip to main content

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.

FieldTypeDescription
version1Payload format. Any other version fails.
appmailmaskApp discriminator. Any other app fails with an interpreter hint.
eventstringEither message-refused for a refusal or test for a CLI test.
titlestringNotification title supplied by Mailmask.
messagestringHuman-readable refusal or test message.
priority1-5Priority level (1 = min, 3 = default, 5 = max).
tagsstring[]ntfy tags: email for refusals and email, test for CLI tests.
occurredAtstringWhen Mailmask created the notification.
detailsobjectStable routing details described below.

The details object has these required string fields:

FieldDescription
aliasResolved alias address without a subaddress tag.
envelopeSenderSMTP envelope sender checked by Mailmask's sender rules.
recipientOriginal SMTP envelope recipient, including a subaddress tag when present.
reasonStable 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:

TitleEvent KeyPriorityTags
Mailmask refused a messagemessage-refused3 (default)email
Mailmask test notificationtest3 (default)email, test

Refusal reasons are disabled, expired, filtered, misconfigured, and the forward-compatible fallback refused. A CLI test uses test.

Context Setup

  1. 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.
  2. Deploy — Choose Deploy, then copy the context's URL and token from the Context reference list it prints.
  3. Add a Mailmask notifier — Run mm notifier add-reverse-proxy, passing the context URL and its token when authentication is enabled.
  4. Send a test — Run mm notifier test reverse-proxy, and check that [Mailmask] Mailmask test notification arrives on the context's topic.
bash
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:

json
{
  "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's title (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 sends 3.
  • Tags: mailmask first, then the payload's tags (mailmask, email for 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:

json
{
  "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:

text
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:

json
{
  "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.