n8n-nodes-mailo-custom

Tor-aware Mailo community nodes for n8n.

What is included

• Mailo Tor Accounts credential
  • stores as many Mailo accounts as you need
  • keeps Tor host/port/timeouts in one place
  • defaults are tuned for your stack: mail.mailo.com:993 and n8n-tor:9050
• Tor Mailo Trigger
  • polling trigger without an external scheduler node
  • default search rules: ["UNSEEN","UNFLAGGED"]
  • formats: Resolved, Simple, Raw
  • optional Flagged after read
  • optional Include Tor Route Metadata
• Tor Mailo
  • action node with Set Flags

Architecture

This package does not route the whole n8n instance through Tor.

Only IMAP traffic from these custom nodes goes through Tor:

1. the credential stores the Mailo accounts
2. each account gets its own SOCKS5 connection
3. each account gets its own SOCKS auth/session key for Tor circuit isolation
4. Mailo IMAP is reached only through that Tor-aware transport

This keeps the server IP out of IMAP requests while still letting you manage everything from the n8n UI.

Important behavior

• v0.1.5 is Mailo-only
• v0.1.5 uses polling, not IMAP IDLE
• transient Tor/IMAP polling errors are logged and skipped instead of forcing n8n to reactivate the whole workflow
• when n8n closes the trigger, the polling interval is stopped and late results are not emitted
• repeated transient failures now trigger Mailo self-healing:
  • per-account consecutive failure tracking
  • Tor NEWNYM recovery when the threshold is reached
  • session generation bump for the affected account/mailbox
  • soft background session rotation no more than once per hour
• legacy credentials that still use the original transport defaults are auto-upgraded at runtime:
  • Use Remote DNS becomes false
  • connection/auth timeout becomes 45000ms
  • socket timeout becomes 60000ms
  • Concurrency Limit becomes 1
• when a fragile SOCKS/TLS path fails, the node retries once through a locally resolved Mailo IP before giving up
• the trigger now performs an internal backlog check before every fetch:
  • it first counts messages matching the configured search rules
  • it then fetches the same backlog with full bodies
  • if the backlog exists but fetch returns nothing, it treats this as a trigger stall and advances recovery state
• the trigger emits a bounded heartbeat log every 15 minutes by default, plus whenever it fetches messages
• a poll that stays active for too long is treated as stuck; the trigger starts a recovery poll and ignores late results from the stale cycle
• duplicate prevention is designed around:
  • trigger reads UNSEEN + UNFLAGGED
  • workflow processes the email
  • email becomes Flagged after successful fetch if that option is enabled
• after you change the credential, restart the workflow so the trigger reloads the account list

Concurrency Limit

Concurrency Limit is not the number of accounts in your list.

It only means how many accounts may be checked in parallel during one polling cycle.

Examples:

• Concurrency Limit = 3 and 2 accounts in the credential -> it checks 2
• Concurrency Limit = 3 and 50 accounts in the credential -> it checks 3 at a time until all are done

The next account starts as soon as one active slot finishes. There is no artificial fixed delay between accounts.

Installing in n8n

In self-hosted n8n:

1. open Settings -> Community Nodes
2. install package:
   • n8n-nodes-mailo-custom
3. refresh the editor after installation if needed

Runtime requirements

This package expects a working SOCKS5 Tor endpoint.

Minimum requirement:

• a reachable Tor SOCKS proxy, for example n8n-tor:9050

Without that, the node will not be able to connect to Mailo IMAP and polling will fail.

Optional but recommended for v0.1.5 self-healing recovery:

• Tor ControlPort
• Tor control authentication
• runtime env vars on the n8n-server container

If ControlPort is not configured:

• the package still works in normal polling mode
• session generation rotation still works
• but automatic NEWNYM recovery will log a warning and be skipped
• the trigger writes one startup message explaining that it is running in limited recovery mode

If ControlPort is configured and reachable:

• the trigger writes one startup message confirming full recovery mode
• repeated transient failures can request NEWNYM
• logs include failure count, session generation, and current recovery mode

So:

• no Tor SOCKS at all -> package will fail to work
• Tor SOCKS without ControlPort -> package works, but recovery is partial
• Tor SOCKS with ControlPort -> full v0.1.5 recovery behavior

Configuring the credential

Create Mailo Tor Accounts and fill:

• Tor Host: usually n8n-tor
• Tor Port: usually 9050
• Use Remote DNS: false
• Mailo Host: mail.mailo.com
• Mailo Port: 993
• Use TLS: true

Inside Accounts, add as many Mailo accounts as you want:

• Label
• Email / Login
• Password
• Notes (optional)

Using the trigger

Typical setup:

1. add Tor Mailo Trigger
2. select Mailo Tor Accounts
3. set:
   • Mailbox Name = INBOX
   • Format = Resolved
   • Custom Email Rules = ["UNSEEN","UNFLAGGED"]
4. process the message downstream

Output fields

The trigger keeps fields needed for downstream processing, especially:

• uid
• attributes.uid
• mailbox
• mailoTor.accountKey

If Include Tor Route Metadata is enabled, it also adds:

• mailoTor.routeIp
• mailoTor.isTor

This performs an extra route check request through Tor, so it is optional by design.

Flagged after read

If Flagged after read is enabled, the trigger sets \\Flagged after the message has been fetched successfully.

This is intended for the common pattern:

• search only UNSEEN + UNFLAGGED
• verify in the mailbox that the mail was processed
• avoid pulling the same message twice

Action = Mark as Read stays separate and still controls \\Seen.

Using Set Flags

Tor Mailo can still be used as a separate action node when you want manual control over flags.

It uses:

• uid
• mailbox
• mailoTor.accountKey

from the upstream item whenever possible.

Credential test and Tor route

Credential test:

• checks IMAP login through Tor
• checks route through https://check.torproject.org/api/ip

The UI may only show "Connection tested successfully", so if you want route details per item, enable Include Tor Route Metadata in the trigger.

Tor recovery environment

For self-healing recovery without restarting containers, the Mailo trigger can use Tor ControlPort.

Recommended runtime env vars on the n8n-server container:

MAILO_TOR_CONTROL_HOST=n8n-tor
MAILO_TOR_CONTROL_PORT=9051
MAILO_TOR_CONTROL_PASSWORD=replace-with-a-strong-secret
MAILO_TOR_RECOVERY_FAILURE_THRESHOLD=3
MAILO_TOR_RECOVERY_COOLDOWN_MS=600000
MAILO_TOR_SESSION_ROTATION_MS=3600000
MAILO_TOR_HEARTBEAT_MS=900000
MAILO_TOR_BACKLOG_STALL_THRESHOLD=2
MAILO_TOR_POLL_HARD_TIMEOUT_MS=300000

Optional fallback if you prefer Tor cookie auth instead of a control password:

MAILO_TOR_CONTROL_COOKIE_PATH=/var/lib/tor-control/control_auth_cookie

These are runtime settings only. They do not change the credential UX in n8n.

Recommended Tor config example:

Log notice file /var/log/tor/notices.log
DataDirectory /var/lib/tor
SocksPort 0.0.0.0:9050 IsolateSOCKSAuth
ControlPort 0.0.0.0:9051
HashedControlPassword <tor-hash>

This is infrastructure-level configuration. It is not stored inside the n8n credential.

Publishing updates

Typical Git Bash flow:

cd "/c/Users/narzo/OneDrive/Desktop/Antigravirty Projects/Mailo_reader"
npm login
npm whoami
npm publish

If you already have a valid npm session, you usually only need:

cd "/c/Users/narzo/OneDrive/Desktop/Antigravirty Projects/Mailo_reader"
npm publish

Smoke test

Local helper script:

npm run smoke:test

Expected env vars:

MAILO_TOR_HOST=127.0.0.1
MAILO_TOR_PORT=9050
[email protected]
MAILO_1_PASSWORD=...
[email protected]
MAILO_2_PASSWORD=...

The script:

• checks Tor route
• logs into both mailboxes
• performs IMAP search with ["UNSEEN","UNFLAGGED"]
• prints the first matching UID