Custom SMTP to Webhook

Why Route Custom SMTP Emails to a Webhook?

Custom SMTP setups are used by applications that relay outbound email through their own mail server or a self-managed SMTP gateway, and need to receive replies or inbound messages programmatically. While Custom SMTP 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 — Custom SMTP inbound handler (LMTP/Milter) — 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 SMTP messages through JsonHook instead of relying on the native alternative:

• Limitation avoided: Custom SMTP servers built for sending do not have inbound mail processing capabilities — receiving replies requires either a separate MX configuration or a reply-to redirect strategy.
• Limitation avoided: Building an inbound SMTP handler that processes MIME messages, extracts attachments, and delivers them reliably to an application endpoint is a multi-week engineering project.
• Limitation avoided: Self-managed SMTP relays lack built-in retry logic for inbound event delivery — if the downstream application is unreachable, the message may be bounced rather than retried.
• 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 Custom SMTP inbound handler (LMTP/Milter) 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 SMTP messages without the fragility of raw SMTP or polling-based API integrations.

How to Forward Custom SMTP to JsonHook

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

1. Set the Reply-To header in your outgoing SMTP messages to your JsonHook inbound address (e.g. Reply-To: [email protected]). This ensures that all replies go directly to JsonHook without requiring server-side forwarding configuration.
2. Alternatively, on your Postfix server add an alias in /etc/aliases or /etc/postfix/virtual: [email protected] [email protected], then run postalias /etc/aliases or postmap /etc/postfix/virtual and reload Postfix.
3. For Exim, add a router that redirects matching addresses to your JsonHook address using a redirect router definition.
4. Send a test message to the configured address and verify the webhook payload arrives at your endpoint with the expected fields.

Once forwarding is active, every email that arrives in your Custom SMTP 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 SMTP 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 SMTP settings. That is all the infrastructure you need to stand up.

Custom SMTP vs Custom SMTP inbound handler (LMTP/Milter)

When developers first explore email-to-webhook automation they typically discover Custom SMTP inbound handler (LMTP/Milter) — 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 Custom SMTP inbound handler (LMTP/Milter) 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 SMTP email arrives — no polling, no credential rotation, no MIME parsing, and no bespoke retry code to maintain.

JSON Payload Example

When a Custom SMTP 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 SMTP 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.

Node.js handler for custom SMTP messages forwarded through JsonHook:

import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json());

app.post('/webhooks/smtp', (req, res) => {
  const sig = req.headers['x-jsonhook-signature'] as string;
  const body = JSON.stringify(req.body);
  const expected = crypto
    .createHmac('sha256', process.env.JSONHOOK_SECRET!)
    .update(body).digest('hex');
  if (sig !== expected) return res.status(401).send('Forbidden');

  const msg = req.body;
  // Legacy system bridge: email-in → REST API out
  fetch('https://api.yoursystem.com/inbound', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${process.env.API_KEY}` },
    body: JSON.stringify({ sender: msg.from.address, message: msg.textBody })
  });
  res.sendStatus(200);
});

app.listen(3000);

Common Custom SMTP to Webhook Use Cases

Custom SMTP setups are common in applications that send transactional email through their own mail relay, whether that is Postfix running on a VPS, a corporate SMTP gateway, or an SMTP relay service without native inbound capabilities. JsonHook enables inbound webhook delivery for any SMTP setup that supports email aliases or forwarding.

• Application reply-to routing: Applications that send emails via a custom SMTP relay with a reply-to header pointing at a JsonHook address can capture customer replies as webhooks without any additional mail server configuration.
• Transactional email feedback loops: Forward bounce, complaint, and out-of-office messages received at your SMTP relay to a webhook that automatically updates sending lists and suppresses bad addresses.
• Internal notification relay: Corporate SMTP gateways that distribute internal alerts and notifications can forward copies of key message categories to a webhook for logging, escalation, or integration with chat platforms.
• Email-to-API bridge for legacy systems: Legacy applications that can only communicate via SMTP can send structured data as email to a JsonHook address, which parses the message and fires a webhook to a modern REST API — effectively bridging old and new systems without modifying the legacy application.