Custom IMAP to Webhook

Why Route Custom IMAP Emails to a Webhook?

Custom IMAP email accounts are hosted on self-managed mail servers or third-party hosting providers that expose standard IMAP access for programmatic email retrieval. While Custom IMAP is a capable email platform, its native tooling for programmatic automation was not built for developers who need structured, reliable data delivery to backend systems.

The native approach — IMAP IDLE polling — introduces significant operational overhead. You need to manage credentials, poll or maintain persistent connections, and write custom parsing logic for every message field you care about. When your team is moving fast, that friction adds up to hours of maintenance per integration.

JsonHook eliminates that overhead by accepting inbound mail on your behalf and immediately firing a structured JSON payload to any HTTPS endpoint you specify. The email is parsed, attachments are base64-encoded, and headers are normalised — so your webhook handler can focus entirely on business logic rather than MIME parsing.

Below are the core benefits of routing your Custom IMAP messages through JsonHook instead of relying on the native alternative:

• Limitation avoided: IMAP polling requires a persistent background process that authenticates, selects a folder, issues IDLE commands, and handles reconnections — significant complexity for a simple new-message trigger.
• Limitation avoided: IMAP IDLE is not universally supported; many servers only support polling via NOOP, introducing latency between message arrival and processing.
• Limitation avoided: Writing a robust IMAP poller that handles connection drops, UID sequences, and concurrent access across multiple mailboxes is a non-trivial engineering effort.
• Zero-polling architecture: JsonHook pushes to your endpoint the moment mail arrives — no long-running background jobs needed.
• Automatic attachment handling: PDFs, images, and other file types are extracted, base64-encoded, and included in the JSON payload with their original MIME type.
• Retry with exponential back-off: If your endpoint is temporarily unavailable, JsonHook retries automatically — something the IMAP IDLE polling does not do natively.
• Webhook signatures for security: Every delivery includes an HMAC-SHA256 signature header so you can verify the payload originated from JsonHook.

Whether you are building a support-ticket ingestion pipeline, a lead-capture workflow, or an automated document processor, JsonHook gives you a consistent, typed interface to Custom IMAP messages without the fragility of raw SMTP or polling-based API integrations.

How to Forward Custom IMAP to JsonHook

Getting Custom IMAP emails delivered to your webhook takes about five minutes. The process has two parts: creating a JsonHook address via the API, and configuring Custom IMAP to forward a copy of each incoming message to that address.

1. On your mail server, configure a Sieve filter or an email alias that forwards matching messages to your JsonHook inbound address. For Postfix, add a virtual alias: [email protected] [email protected].
2. If your server uses Dovecot with Sieve, create a rule file: redirect "[email protected]"; in the appropriate Sieve script.
3. For cPanel or Plesk hosting, use the Email Forwarders section to add a forwarder from your mailbox to your JsonHook address.
4. Test by sending a message to the source address and confirming a webhook fires at your endpoint with the correctly parsed JSON payload.

Once forwarding is active, every email that arrives in your Custom IMAP inbox (or matches your filter) will be relayed to your JsonHook address, parsed, and delivered to your endpoint as a JSON payload within seconds.

You can create your JsonHook inbound address with a single curl command. Replace YOUR_API_KEY with the key from your dashboard and set webhookUrl to your endpoint:

curl -X POST https://jsonhook.com/api/addresses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Custom IMAP inbound",
    "webhookUrl": "https://your-app.example.com/webhooks/email",
    "secret": "a-random-signing-secret"
  }'

The response includes your unique @in.jsonhook.com address. Copy that address and paste it into the forwarding field in your Custom IMAP settings. That is all the infrastructure you need to stand up.

Custom IMAP vs IMAP IDLE polling

When developers first explore email-to-webhook automation they typically discover IMAP IDLE polling — the official programmatic route provided by Self-hosted / Any Provider. The table below shows how it compares to using JsonHook as an intermediary.

The native approach through IMAP IDLE polling requires you to set up OAuth credentials or API keys, maintain a long-running listener or polling job, write your own MIME parser, and implement your own retry queue. Any one of those steps can become a reliability bottleneck in production.

JsonHook handles all of that infrastructure on your behalf. You get a single HTTPS webhook call with a predictable JSON schema every time a Custom IMAP email arrives — no polling, no credential rotation, no MIME parsing, and no bespoke retry code to maintain.

JSON Payload Example

When a Custom IMAP email is forwarded to your JsonHook address and delivered to your endpoint, the request body looks like the following. All fields are consistently present; optional fields such as htmlBody and attachments are included when the source message contains them.

{
  "id": "msg_01j8xkr4p2vn3q7w",
  "receivedAt": "2026-03-15T14:32:07.412Z",
  "from": {
    "name": "Alice Smith",
    "address": "[email protected]"
  },
  "to": [
    {
      "name": "",
      "address": "[email protected]"
    }
  ],
  "subject": "Your Custom IMAP message subject here",
  "textBody": "Plain-text content of the email body.",
  "htmlBody": "<div>HTML version of the email body.</div>",
  "headers": {
    "message-id": "<[email protected]>",
    "x-mailer": "Self-hosted / Any Provider",
    "mime-version": "1.0"
  },
  "attachments": [
    {
      "filename": "document.pdf",
      "contentType": "application/pdf",
      "size": 84234,
      "content": "JVBERi0xLjQK..."
    }
  ],
  "spf": "pass",
  "dkim": "pass"
}

The id field is a unique, stable identifier you can use for idempotent processing. The spf and dkim fields reflect the authentication results JsonHook observed when receiving the message, which you can use to enforce additional trust policies in your handler.

Attachment content is standard base64. Decode it with a single call in any language — Buffer.from(att.content, 'base64') in Node.js, base64.b64decode(att.content) in Python, and so on.

Python handler for custom IMAP messages forwarded through JsonHook:

import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)

@app.route('/webhooks/imap', methods=['POST'])
def handle():
    sig = request.headers.get('X-JsonHook-Signature', '')
    body = request.get_data()
    expected = hmac.new(
        os.environ['JSONHOOK_SECRET'].encode(),
        body, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(sig, expected):
        abort(401)

    msg = request.json
    to_addr = msg['to'][0]['address'] if msg.get('to') else ''
    # Route by recipient for shared-mailbox multi-tenancy
    if 'billing' in to_addr:
        print(f"Billing email: {msg['subject']}")
    elif 'support' in to_addr:
        print(f"Support email: {msg['subject']}")
    return '', 200

Common Custom IMAP to Webhook Use Cases

Custom IMAP accounts are used by businesses and developers who run their own mail server or use a hosting provider that exposes standard IMAP access. Polling IMAP for new messages requires persistent connections, folder monitoring, and UID tracking — all of which are replaced by JsonHook's push-based webhook delivery through a simple forwarding rule.

• Self-hosted mail server automation: Teams running Postfix, Dovecot, or Mailcow can configure a simple Sieve filter or alias to forward selected messages to a JsonHook address, giving them webhook delivery without modifying their mail server software.
• Shared mailbox monitoring: Businesses with shared billing@, support@, or info@ IMAP mailboxes can forward every incoming message to a webhook for unified routing without polling each account separately.
• Multi-domain inbox aggregation: Organisations that operate multiple domains on the same IMAP server can forward all inbound messages to a single JsonHook webhook and route them internally by to address.
• Attachment extraction pipeline: Businesses that receive data files (CSV, XML, PDF) via email can use a webhook to automatically extract and process attachments without writing a custom IMAP poller and MIME parser.