MailWebhook n8n Connector

n8n-nodes-mailwebhook receives MailWebhook email events in n8n with signature verification enabled by default and explicit attachment actions.

Current status: trigger and attachment operations are implemented and locally validated. The packed package has been exercised in a real n8n 2.36.9 scratch runtime through authenticated editor metadata, credential, workflow, manual-run, public test-webhook, and activated /webhook/{webhookId}/mailwebhook paths, with a mock MailWebhook API boundary for attachment URL and binary download operations.

What the connector adds beyond the generic Webhook node

• Verifies X-MailWebhook-Signature without requiring a Code node.
• Exposes MailWebhook metadata such as verification status, payload mode, idempotency key, event ID, route ID, and message ID.
• Preserves Generic JSON and Custom JSON payloads as raw JSON rather than forcing a lossy typed shape.
• Adds a convenience common view only for Generic JSON email fields.
• Resolves temporary attachment download URLs through the MailWebhook API.
• Downloads attachments as n8n binary data only when an explicit Attachment node is used.

Nodes

MailWebhook Trigger

Use this as the workflow trigger for MailWebhook HTTPS routes.

Defaults:

• Require Signature Verification: enabled.
• Include Request Headers: disabled.
• Include Raw Body: disabled.

Output shape:

{
  "payload": {},
  "mailwebhook": {
    "verified": true,
    "payloadMode": "generic",
    "idempotencyKey": "...",
    "eventId": "...",
    "routeId": "...",
    "messageId": "<message@example.com>",
    "signature": {
      "kid": "...",
      "timestamp": 1788160000,
      "ageSeconds": 1
    },
    "receivedAt": "2026-08-31T00:00:00.000Z"
  },
  "common": {
    "subject": "Hello",
    "from": [],
    "to": [],
    "text": "...",
    "html": "...",
    "attachments": []
  }
}

For Custom JSON payloads, payload is preserved and mailwebhook.payloadMode is custom. The connector does not invent typed fields for custom payloads.

MailWebhook Attachment

Use this after the trigger when a workflow needs attachment content.

Operations:

• Get Temporary Download URL: calls GET /v1/messages/{message_id}/attachments/{attachment_id}/url and returns the MailWebhook URL response.
• Download Attachment as Binary: resolves a URL, downloads the file without sending the API key to the returned URL, and writes n8n binary data.

Default expressions when connected after the trigger:

messageId: {{$json.mailwebhook?.messageId || $json.payload?.message?.message_id || $json.payload?.data?.message?.message_id || $json.messageId}}
attachmentId: {{$json.common?.attachments?.[0]?.id || $json.payload?.body?.attachments?.[0]?.id || $json.payload?.attachments?.[0]?.id || $json.payload?.data?.message?.attachments?.[0]?.id || $json.attachmentId}}

See docs/attachment-contract.md.

Credentials

MailWebhook Signing API

Used only by the trigger.

• Add one or more signing keys with kid and signing secret.
• Leave timestamp tolerance at the default 300 seconds unless your clocks require a different value.

MailWebhook API

Used only by attachment operations.

• API Key: MailWebhook project API key.
• API Base URL: defaults to https://app.mailwebhook.com.

Starter workflow

Import workflows/mailwebhook-starter.json into n8n. It contains:

1. MailWebhook Trigger with signature verification enabled.
2. An IF branch that checks whether Generic JSON has attachments.
3. MailWebhook Attachment URL resolution for the first attachment.
4. No-op downstream placeholders that users replace with their own actions.

See docs/starter-workflow.md.

Deliberate v1 deferrals

• Duplicate suppression is deferred because it requires connector-managed state and can break replay semantics.
• Event replay action is deferred because the n8n-specific value is not yet clear.
• Full MailWebhook admin API coverage is out of scope.
• The trigger intentionally does not download attachments or perform network calls beyond signature verification.

Development

npm install
npm run lint
npm run typecheck
npm test
npm run build
npm run pack:dry-run
npm run test:acceptance:n8n

The package must keep runtime dependencies empty for n8n verified community-node eligibility. npm run test:acceptance:n8n is the heavier local public-interface acceptance check and requires python3, curl, npx, and enough time to start a scratch n8n runtime. It packs the connector, installs that tarball into n8n, creates credentials and workflows through REST APIs, exercises /webhook-test, activates a workflow, and exercises /webhook with signed and tampered deliveries.

Validation evidence

• docs/scaffold-validation.md
• docs/runtime-acceptance.md
• docs/live-workflow-acceptance.md
• docs/e2e-validation-report.md
• docs/validation-traceability.md
• docs/release-readiness.md
• docs/compatibility.md
• docs/package-audit.md
• docs/release.md
• docs/n8n-verification-submission.md
• docs/manual-qa-checklist.md

Security and troubleshooting

• docs/security.md
• docs/troubleshooting.md
• docs/examples.md