Inbound Webhooks

When an inbound email matches a route whose actions include webhook, MailLand sends the parsed email to that route's webhook as a JSON POST request. This page covers the payload format, signature verification, and delivery behavior.

Webhook PayloadCopy Anchor Link

MailLand sends a POST request to your webhook URL with the following JSON body:

{
  "event": "inbound.received",
  "event_id": "evt_a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "timestamp": "2026-02-17T14:30:00Z",
  "occurred_at": "2026-02-17T14:29:58Z",
  "schema_version": 1,
  "data": {
    "idempotency_key": "k7m2x9q4p1w8z3_r7k3m9q2p4w8x1",
    "email": {
      "id": "k7m2x9q4p1w8z3",
      "received_at": "2026-02-17T14:29:58Z",
      "size_bytes": 48213,
      "envelope": {
        "from": "[email protected]",
        "to": ["[email protected]"]
      },
      "headers": {
        "from": { "address": "[email protected]", "name": "Jane Customer" },
        "to": [{ "address": "[email protected]", "name": null }],
        "cc": [],
        "subject": "Need help with my account",
        "message_id": "<[email protected]>",
        "in_reply_to": null,
        "reply_to": "[email protected]",
        "date": "2026-02-17T14:29:55Z"
      },
      "body": {
        "text_preview": "I need assistance with my account settings.",
        "has_text": true,
        "has_html": true
      },
      "attachments": [
        {
          "id": "a3k7m2q9p4w1x8",
          "file_name": "screenshot.png",
          "content_type": "image/png",
          "size_bytes": 34500,
          "is_inline": false,
          "content_id": null,
          "download_url": "https://r2.example.com/screenshot.png?X-Amz-Signature=..."
        }
      ],
      "authentication": {
        "spf": { "result": "pass" },
        "dkim": { "result": "pass" },
        "dmarc": { "result": "pass" }
      },
      "spam": {
        "score": 1.2,
        "is_spam": false,
        "reason": null
      },
      "source": {
        "ip": "203.0.113.42",
        "hostname": "mail.example.com"
      }
    },
    "matched_route": {
      "id": "r7k3m9q2p4w8x1",
      "name": "Support Inbox"
    }
  }
}

The full email body is never included inline: only a truncated text_preview and the has_text/ has_html flags. There is no body.html field.

Fields without a value (name, in_reply_to, content_id, reason, data.matched_route, and so on) are omitted from the JSON entirely rather than sent as null. The sample above shows null for readability; do not rely on the key being present.

Payload FieldsCopy Anchor Link

AttachmentsCopy Anchor Link

Attachment content is never included inline. Each entry in data.email.attachments carries a download_url:

GET https://api.mail.land/v1/transactional/inbound/emails/{emailId}/raw

Signature VerificationCopy Anchor Link

Inbound webhooks are signed exactly like every other MailLand webhook: same header, same scheme, same secret handling. The canonical reference, with a worked example and verifier code in eight languages, is Signature Verification; everything there applies here unchanged.

In short:

X-MLND-Signature: t=1708171200,v1=<hex>

• t is a Unix timestamp in seconds, v1 is a lowercase-hex HMAC-SHA256;
• the signed string is {timestamp}.{raw_body}: the timestamp, a literal period, then the body exactly as received, before JSON parsing;
• the key is the webhook's signing secret, shown once when the webhook is created;
• compare in constant time and reject a timestamp more than 300 seconds old.

Delivery BehaviorCopy Anchor Link

Response CodesCopy Anchor Link

Your endpoint must respond with a 2xx status code to acknowledge receipt. Anything else, a non-2xx status or a timeout, counts as a failed delivery attempt.

Retry PolicyCopy Anchor Link

A failed attempt is retried on the same schedule as every other webhook event, up to 6 attempts total per event: the first attempt, then retries immediately, after 1 minute, 5 minutes, 15 minutes and 1 hour. After the 6th failed attempt, the delivery is marked permanently failed. You can replay it manually. See Retry Logic for the full schedule.

Replay a WebhookCopy Anchor Link

Re-deliver the webhook for a specific inbound email:

POST https://api.mail.land/v1/transactional/inbound/emails/{id}/replay-webhook

curl -X POST https://api.mail.land/v1/transactional/inbound/emails/k7m2x9q4p1w8z3/replay-webhook \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "emailId": "k7m2x9q4p1w8z3",
  "queued": true,
  "webhookUrl": "https://yourapp.com/webhooks/support",
  "message": "Webhook replay queued successfully"
}

This queues one durable delivery to the route's matched webhook and returns 202 Accepted once that row has committed, it does not send synchronously. The replay gets a new event ID (a new event_id and X-MLND-Event-Id) and carries the original delivery's ID in data.replay_of, so your deduplication treats it as a new event while you can still tie it to the original. data.idempotency_key stays the same as the original delivery. The request carries X-MLND-Source: inbound and X-MLND-Inbound-Email-Id, and any attachment download_url in the payload is signed at send time: valid for 15 minutes from then, not from when you called replay.

Deduplicating EventsCopy Anchor Link

Inbound webhook delivery is at-least-once: a retry, a timeout on your side after you already processed the request, or a worker handover can deliver the same event more than once. Receivers must deduplicate.

• Every inbound webhook carries a stable event ID in event_id and the X-MLND-Event-Id header. It is deterministic per inbound message and webhook, so every delivery attempt of the same message to the same webhook has the same ID.
• Deduplicate by that ID. Store the IDs you have processed and skip any ID you have seen.
• A manual replay is a new event. It has a new event_id and a data.replay_of field holding the original ID. If you want a replay to be ignored when the original was already processed, also check data.replay_of against your stored IDs.

app.post("/webhooks/support", express.raw({ type: "application/json" }), async (req, res) => {
  // 1. Verify X-MLND-Signature first (see Signature Verification).
  const eventId = req.header("X-MLND-Event-Id");
  const client = await db.connect();
  try {
    await client.query("BEGIN");
    // 2. Record the event id; the unique constraint makes this atomic.
    const inserted = await client.query(
      "INSERT INTO processed_events (event_id) VALUES ($1) ON CONFLICT (event_id) DO NOTHING",
      [eventId],
    );
    // 3. Only a first-time id enqueues work, in the SAME transaction (jobs table).
    if (inserted.rowCount > 0) {
      await client.query("INSERT INTO jobs (kind, payload) VALUES ($1, $2)", [
        "process-inbound-email",
        req.body.toString(),
      ]);
    }
    await client.query("COMMIT");
    res.sendStatus(200); // new or duplicate: acknowledge
  } catch (err) {
    await client.query("ROLLBACK"); // id and job are both undone, so the retry is not a "duplicate"
    res.sendStatus(500);
  } finally {
    client.release();
  }
});

Recording the ID and enqueuing the work in one transaction matters: if the ID were saved first and the enqueue then failed, MailLand's retry would be skipped as a duplicate and the email would be lost.

Keep processed IDs for at least as long as your longest retry window plus any replay you may trigger.

Webhook HeadersCopy Anchor Link

Every webhook request includes these headers:

Best PracticesCopy Anchor Link

• Respond quickly: acknowledge the webhook with 200 immediately and process the email asynchronously in a background job.
• Verify signatures: always validate the X-MLND-Signature header to prevent spoofed payloads.
• Handle duplicates: delivery is at-least-once, so deduplicate by X-MLND-Event-Id (the payload event_id). A manual replay has a new ID and data.replay_of set to the original; see Deduplicating Events.
• Download attachments immediately: each download_url expires 15 minutes after the payload is generated; after that, fetch the raw message instead.
• Use HTTPS: webhook URLs must use HTTPS in production for secure payload delivery.

Error ResponsesCopy Anchor Link

Next StepsCopy Anchor Link

• Inbound Overview: configure inbound settings and view emails
• Inbound Routes: set up routing rules for webhook delivery
• Webhooks: outbound webhook configuration for email events