March 26, 2026

How to Receive Inbound Email via Webhook

Set up webhook-based inbound email for your AI agent. Register a webhook, verify signatures, parse messages, and reply in-thread.

Your AI agent can send email. Now it needs to hear back. This tutorial shows how to receive inbound email via webhooks using Robotomail. When someone replies to your agent, the message arrives at your endpoint as a structured JSON payload, ready to process.

Three ways to receive email

Robotomail supports three inbound delivery methods:

Webhooks (push). We POST the message to your URL. Best for server-based agents with a public endpoint.
SSE streaming (push, no public URL). Connect to GET /v1/events and receive messages as server-sent events. Best for agents running locally or behind a firewall.
Polling (pull). Call GET /v1/mailboxes/:id/messages on your own schedule. Simplest to implement but adds latency.

This guide focuses on webhooks, the most common pattern for production agents.

Step 1: Register a webhook

Tell Robotomail where to send inbound messages. You can scope a webhook to a specific mailbox or receive events for all mailboxes on your account.

curl

curl -X POST https://api.robotomail.com/v1/webhooks \
  -H "Authorization: Bearer rm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/email",
    "events": ["message.received"],
    "mailboxId": "mbx_abc123"
  }'

# Response includes your webhook secret:
# {
#   "id": "wh_xyz789",
#   "secret": "whsec_...",
#   "url": "https://your-app.com/webhooks/email",
#   "events": ["message.received"]
# }

Save the secret value. You'll use it to verify that incoming webhook payloads are genuinely from Robotomail.

Step 2: Build your endpoint

Your webhook endpoint receives a POST request with the full message payload. Here's what the payload looks like:

webhook payload

{
  "event": "message.received",
  "data": {
    "id": "msg_abc123",
    "mailboxId": "mbx_abc123",
    "threadId": "thr_xyz789",
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Re: Hello from my AI agent",
    "bodyText": "Sounds great, let's schedule a call.",
    "bodyHtml": "<p>Sounds great, let's schedule a call.</p>",
    "receivedAt": "2026-03-26T14:30:00Z",
    "attachments": []
  }
}

Step 3: Verify the signature

Every webhook delivery includes an X-Robotomail-Signature header containing an HMAC-SHA256 signature. Always verify this before processing the payload.

python

import hmac
import hashlib

def verify_signature(payload_bytes, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload_bytes,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

typescript

import { createHmac, timingSafeEqual } from "crypto";

function verifySignature(
  payloadBody: string,
  signature: string,
  secret: string,
): boolean {
  const expected = createHmac("sha256", secret)
    .update(payloadBody)
    .digest("hex");
  return timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature),
  );
}

Step 4: Process and reply

Once verified, parse the message and generate a reply. The threadId and id fields let you reply in-thread so the conversation stays connected in the recipient's email client.

python (complete handler)

@app.route("/webhooks/email", methods=["POST"])
def handle_inbound():
    # 1. Verify signature
    signature = request.headers.get("X-Robotomail-Signature", "")
    if not verify_signature(request.data, signature, WEBHOOK_SECRET):
        return "Invalid signature", 401

    # 2. Parse the message
    payload = request.json
    message = payload["data"]

    # 3. Generate reply (your LLM logic here)
    reply = generate_reply(
        from_addr=message["from"],
        subject=message["subject"],
        body=message["bodyText"],
        thread_id=message["threadId"],
    )

    # 4. Send reply, threaded to the inbound message
    requests.post(
        f"{BASE_URL}/mailboxes/{message['mailboxId']}/messages",
        headers=headers,
        json={
            "to": [message["from"]],
            "subject": f"Re: {message['subject']}",
            "bodyText": reply,
            "inReplyTo": message["id"],
        },
    )

    return "", 200

Retry behavior

If your endpoint returns a non-2xx status code or times out, Robotomail retries the delivery with exponential backoff. Your endpoint should return a 200 status quickly and process the message asynchronously if needed.

Next steps

You now have a complete inbound email pipeline. For related guides:

Start building, free