n8n-nodes-jmap-packet

JMAP nodes for n8n — mail, mailboxes and threads over JMAP (RFC 8620 / RFC 8621). Tested against Stalwart; also works with Apache James, Twake Mail and Fastmail.

Based on n8n-nodes-jmap by Michel-Marie Maudet (LINAGORA), MIT licensed. This package carries two fixes that are also offered upstream as PR #18 and PR #19; it exists so they can be used before those land, and installs alongside the original rather than replacing it.

What differs from the original

• Method calls go to the session's apiUrl instead of the configured server URL (issue #17). Without this, a credential pointing at the spec's discovery URL (/.well-known/jmap) returns 404 on every method call while the credential test still reports success.
• The trigger can filter which emails it fires on — recipient, sender, subject, full text, attachments, unread, flagged. Previously only the action node could; the trigger fetched up to 100 existing messages on its first run.

Installation

Community Nodes (Recommended)

1. Go to Settings > Community Nodes
2. Select Install
3. Enter n8n-nodes-jmap
4. Agree to the risks and click Install

Manual Installation

cd ~/.n8n/nodes
npm install n8n-nodes-jmap

Then restart n8n.

Authentication

This node supports three authentication methods to connect to JMAP servers.

Method 1: Basic Authentication

The simplest method using email and password directly.

Configuration:

1. Create a new JMAP API credential
2. Set Authentication Method to Basic Auth
3. Fill in:
   • JMAP Server URL: https://jmap.example.com/jmap
   • Email: [email protected]
   • Password: Your password

Use case: Development, testing, or servers without OAuth2 support.

Method 2: Bearer Token

Use a pre-obtained access token (e.g., from an external OAuth2 flow).

Configuration:

1. Create a new JMAP API credential
2. Set Authentication Method to Bearer Token
3. Fill in:
   • JMAP Server URL: https://jmap.example.com/jmap
   • Access Token: Your JWT or access token

Use case: Integration with existing authentication systems, tokens obtained via scripts or other workflows.

Method 3: OAuth2 / OIDC with PKCE

Full OAuth2 Authorization Code flow with PKCE (Proof Key for Code Exchange). This is the recommended method for production as it provides:

• Automatic token refresh
• No password storage in n8n
• Secure SSO integration

Configuration:

1. Create a new JMAP OAuth2 API credential
2. Fill in:
   • Client ID: Your OIDC client ID
   • Client Secret: Leave empty for public clients (PKCE)
   • Authorization URL: https://sso.example.com/oauth2/authorize
   • Access Token URL: https://sso.example.com/oauth2/token
   • JMAP Server URL: https://jmap.example.com/jmap
3. Click Connect to initiate the OAuth2 flow
4. Log in with your SSO credentials

Compatible Identity Providers:

• LemonLDAP::NG
• Keycloak
• Auth0
• Any OAuth2/OIDC compliant provider

Example: LemonLDAP::NG Configuration

Authorization URL: https://sso.example.com/oauth2/authorize
Access Token URL:  https://sso.example.com/oauth2/token
Client ID:         my-n8n-client
Scope:             openid email profile offline_access

Example: Keycloak Configuration

Authorization URL: https://keycloak.example.com/realms/myrealm/protocol/openid-connect/auth
Access Token URL:  https://keycloak.example.com/realms/myrealm/protocol/openid-connect/token
Client ID:         n8n-jmap-client
Scope:             openid email profile offline_access

Choosing a trigger

Two triggers, and the polling one is the right default.

| | JMAP Trigger (polling) | JMAP Push Trigger | |---|---|---| | How it learns of new mail | asks every few minutes | the server posts to a URL | | Needs n8n reachable from the mail server | no | yes | | Latency | the poll interval | seconds | | Setup | credential only | credential plus a reachable https URL |

Polling needs nothing from your network beyond an outbound connection, which is why it is the default. Push is worth it when the delay matters — an inbox that feeds a ticket system, a scan folder someone is waiting on.

What push requires

The mail server has to be able to reach the URL n8n offers for this workflow, over https, with a certificate it accepts. JMAP servers commonly refuse a bare IP address and want a hostname; if you are on Tailscale, tailscale cert issues a real certificate for your MagicDNS name, which works. Set N8N_WEBHOOK_URL so n8n hands out the address the mail server can actually use.

The node refuses to register anything that is not https rather than letting the server reject it later with a message you would have to go looking for.

There is also a handshake: on registration the server posts a verification code, which the node echoes back. Until that completes nothing else arrives. It happens on its own — worth knowing only because it explains why the first message after activating a workflow is not an email.

Once the path is reachable, the webhook URL is the only thing guarding it. It contains a UUID, so it is not guessable, but it is not a secret either: it goes to the mail server, and it passes through n8n's own logs, proxy access logs and any workflow export. The node therefore does not trust what arrives there. It confirms only the subscription it registered itself — a body naming a different one is ignored rather than acted on — and it acts on a state change only after the handshake has completed.

If n8n sits behind an authenticating reverse proxy — SSO, an OIDC gateway, HTTP basic auth — the mail server cannot get past it. It is not a browser, it has no session, and it will be handed a login page instead of your workflow; the subscription then never finishes verifying and no push ever arrives. Exempt the webhook path from authentication: /webhook/*, and /webhook-test/* as well if you want manual test executions to receive pushes. The alternative is to give N8N_WEBHOOK_URL an address that does not pass through the proxy at all.

What a push actually delivers

A push carries a state string, not a message. RFC 8620 section 7.1 is explicit about this: a StateChange notification says which types moved, and points at the /changes methods to find out what that means.

So the node asks. On a notification it calls Email/changes with the state it last recorded, gets back the ids that were created, and fetches those. No timestamp is involved anywhere — two messages arriving in the same second cannot hide each other, and a server that caps its answer sets hasMoreChanges, which the node pages through rather than silently truncating.

The state is recorded when the subscription is registered, so switching a workflow on does not hand you the mailbox you already have.

Transport security

The server URL must use https. A credential pointing at http:// is refused, with the single exception of loopback addresses so local development keeps working.

This is not a formality. The session resource is where the server tells the client where everything else lives — the API endpoint, the download endpoint. Over plain HTTP anyone on the network path can rewrite that answer and point the node somewhere else, and can read the credential off the wire while they are at it. There is nothing a client can do about either, which is why discovery over HTTP is not supported at all rather than supported with caveats.

Over https the node follows what the session says, including an apiUrl or downloadUrl on a different host. That is deliberate: RFC 8620 section 2 provides for a domain pointing at a provider elsewhere, and refusing it would break ordinary autodiscovery. The trust boundary is the TLS connection to the server the credential belongs to — a server that already holds your credential gains nothing by naming another address.

Restricting which addresses n8n may reach at all — internal ranges, metadata endpoints — is a platform-level control, not something an individual node should reimplement. n8n has one: N8N_SSRF_PROTECTION_ENABLED=true. It is off by default so that self-hosted instances can keep calling internal services; turn it on if your n8n talks to services on the public internet.

Nodes

JMAP Node

Main node for email operations.

| Resource | Operation | Description | |----------|-----------|-------------| | Email | Send | Send a new email | | Email | Reply | Reply to an existing email | | Email | Get | Retrieve an email by ID | | Email | Get Many | List emails with advanced search filters | | Email | Get Attachments | Download attachments as binary data | | Email | Create Draft | Create a draft without sending | | Email | Delete | Delete an email | | Email | Mark as Read | Mark email as read | | Email | Mark as Unread | Mark email as unread | | Email | Move | Move email to another mailbox | | Email | Add Label | Add a mailbox label to an email | | Email | Remove Label | Remove a mailbox label from an email | | Email | Get Labels | Get all labels for an email | | Mailbox | Get | Get mailbox details by ID | | Mailbox | Get Many | List all mailboxes | | Thread | Get | Get thread details by ID | | Thread | Get Many | Get all emails in a thread |

JMAP Trigger Node

Polling-based trigger for new emails.

| Event | Description | |-------|-------------| | New Email | Triggers on any new email | | New Email in Mailbox | Triggers on new email in a specific mailbox |

Options:

• Simple Output: Return simplified email data
• Include Attachments Info: Include attachment metadata
• Mark as Read: Automatically mark fetched emails as read

Features

Advanced Email Search

The Get Many operation supports powerful search filters based on JMAP RFC 8621:

| Filter | Description | |--------|-------------| | Received After | Emails received after a specific date | | Received Before | Emails received before a specific date | | From Contains | Filter by sender address | | To Contains | Filter by recipient address | | Subject Contains | Filter by subject line | | Full Text Search | Search in subject, body, and addresses | | Has Attachment | Only emails with attachments | | Unread Only | Only unread emails | | Flagged Only | Only starred/flagged emails |

Combine multiple filters for precise email retrieval.

Attachment Handling

The Get Attachments operation downloads email attachments as binary data, ready to use with other n8n nodes:

• Inline image filtering: Exclude embedded images (signatures, logos) by default
• MIME type filtering: Filter by file type (e.g., application/pdf, image/*)
• Native compatibility: Works seamlessly with n8n's Compression, Google Drive, S3, and other nodes

Example workflow: JMAP Trigger > Get Attachments > Compression (extract ZIP) > Google Drive (upload)

AI Agent Integration

This node can be used as a tool by n8n AI Agents, enabling autonomous email operations.

Setup

1. Ensure you're using n8n version 1.x or later
2. The node will automatically appear in the AI Agent's tool list

Example Use Cases

• Email assistant: Let the AI read, search, and respond to emails
• Automated triage: AI categorizes and labels incoming emails
• Smart notifications: AI analyzes email content and triggers actions

Supported Operations as AI Tool

The AI Agent can use all JMAP operations:

• Search emails with natural language queries
• Read and analyze email content
• Send replies based on context
• Organize emails (labels, folders, flags)
• Download and process attachments

Contributing

Contributions are welcome! This project is open source and we encourage the community to help improve it.

How to Contribute

1. Fork the repository
2. Create a branch for your feature or fix: git checkout -b feature/my-feature
3. Make your changes and test them locally
4. Run linting: npm run lint
5. Commit with a clear message
6. Push to your fork and open a Pull Request

Ideas for Contributions

• Support for additional JMAP capabilities (Calendar, Contacts)
• Improved error handling and messages
• Additional search filters
• Documentation improvements
• Bug fixes and optimizations

Local Development

# Clone your fork
git clone https://github.com/YOUR_USERNAME/n8n-nodes-jmap.git
cd n8n-nodes-jmap

# Install dependencies
npm install

# Build
npm run build

# Development mode (watch)
npm run dev

# Lint
npm run lint

# Format code
npm run format

Testing Locally with n8n

# Start n8n with the local node
N8N_CUSTOM_EXTENSIONS="/path/to/n8n-nodes-jmap" n8n start

JMAP Protocol

JMAP (JSON Meta Application Protocol) is a modern, efficient alternative to IMAP for email access:

• Stateless: No persistent connections required
• JSON-based: Easy to parse and debug
• Efficient: Batched requests, delta sync
• Standardized: RFC 8620 (Core) and RFC 8621 (Mail)

Learn more: jmap.io

License

MIT

Author

Michel-Marie MAUDET

This project is developed with the support of LINAGORA and Twake.