Email intake

How email triggers receive mail

There is no platform-level inbound domain or email provider to configure. Instead, every routine trigger gets its own secret webhook URL:

POST {BACKEND}/webhooks/routine/{secret}

Anyone who can deliver an HTTP POST to that URL — a mail-to-webhook bridge, a forwarding rule in your email provider, a custom script — can trigger the routine. The {secret} is a capability token generated when the trigger is created; knowledge of the URL is the credential. The URL is shown in the routine’s Email trigger section after the first save. Use the copy button to paste it wherever you forward email.

Accepted payload formats

The endpoint accepts three payload formats. Send whichever format your email provider or script produces most naturally.

Raw RFC 822 MIME

Send the raw email bytes with Content-Type: message/rfc822 (or application/octet-stream):

POST /webhooks/routine/{secret}
Content-Type: message/rfc822

<raw MIME bytes>

Mailgun-style multipart

If you forward via Mailgun (or another provider that posts multipart form data), the endpoint extracts the email from a body-mime, email, or message field:

POST /webhooks/routine/{secret}
Content-Type: multipart/form-data

body-mime=<raw MIME bytes>

The field name body-mime is checked first, then email, then message.

JSON

Post a JSON object directly. Only from is required; all other fields are optional:

{
  "from": "sender@example.com",
  "subject": "...",
  "text": "...",
  "html": "...",
  "message_id": "...",
  "attachments": [
    {
      "filename": "report.pdf",
      "content_type": "application/pdf",
      "content_base64": "<base64>"
    }
  ]
}

The from field accepts either a plain address string ("a@b.com") or an object with address and name fields ({ "address": "a@b.com", "name": "Alice" }).

Optional HMAC signing

Enable Webhook signing in the trigger’s settings to require callers to authenticate each delivery. When signing is enabled:

The platform generates a per-trigger signing secret (separate from the URL secret).

Every POST must include an X-Exulu-Signature header:

X-Exulu-Signature: sha256=<HMAC-SHA256(body_bytes, signing_secret)>

Optionally include an X-Exulu-Timestamp header (Unix seconds) for replay defense. The platform rejects timestamps more than 5 minutes from server time.

Requests without a valid signature are rejected with 401. Unsigned deliveries when signing is disabled are accepted.

Delivery mechanics

Persist-before-ACK

Once the payload is parsed and any signature check passes, the platform persists the raw payload to object storage (S3) before returning 200 OK. The intake job is enqueued only after the payload is durably stored. A storage or crash failure returns 5xx — your sender should retry.

Guard chain

After intake, the email runs the same guard chain as any inbound email: auto-reply suppression → sender allowlist → rate limits → Message-ID dedup → filter rules.

Behavior when the trigger is disabled or not found

Condition	Response
Secret not found in database	`404`
Trigger exists but is disabled	`200` (email is silently dropped — no run starts)
Signing enabled, signature missing or invalid	`401`
Timestamp replay (> 5 min skew)	`401`

There is no platform-level kill switch for email delivery. Each trigger is independently enabled or disabled from the routine’s workbench.

Regenerating the webhook URL

Use Regenerate URL in the trigger settings to issue a new secret. The old URL stops working immediately. Update any forwarding rules that point to the old URL before regenerating.

Next steps

Email triggers

Configure sender filters, rate limits, and the guard chain for a routine’s email trigger.

Variables

Store configuration values referenced by agents and integrations.

Users & access

Platform

Governance

How email triggers receive mail

Accepted payload formats

Raw RFC 822 MIME

Mailgun-style multipart

JSON

Optional HMAC signing

Delivery mechanics

Persist-before-ACK

Guard chain

Behavior when the trigger is disabled or not found

Regenerating the webhook URL

Next steps

Email triggers

Variables

​How email triggers receive mail

​Accepted payload formats

​Raw RFC 822 MIME

​Mailgun-style multipart

​JSON

​Optional HMAC signing

​Delivery mechanics

​Persist-before-ACK

​Guard chain

​Behavior when the trigger is disabled or not found

​Regenerating the webhook URL

​Next steps

Email triggers

Variables

How email triggers receive mail

Accepted payload formats

Raw RFC 822 MIME

Mailgun-style multipart

JSON

Optional HMAC signing

Delivery mechanics

Persist-before-ACK

Guard chain

Behavior when the trigger is disabled or not found

Regenerating the webhook URL

Next steps