Destinations and events

Delivered, then gone

mximp is a transform, not a store. A message is deleted once every destination has received it (within the hour; a live test case or an open task keeps it). Deliveries therefore carry the original. See Data.

Holding is the default

A bucket needs no destination. Every capture is stored and readable over MCP and HTTP (list_captures, get_capture), so the ordinary way to use the platform is for your agent to query when it wants to. Add a webhook only when something else must be told the moment a capture applies. Two more destinations, an email forward and a per-bucket digest, follow once sending is enabled.

Failed deliveries

Because holding is the default, a failed webhook is not a lost capture: the capture is intact and the failure is a row under its deliveries. Find them with list_captures and delivery: "failed", fix the endpoint, and deliver_capture sends again. There is no separate queue to drain.

Webhooks

add_destination registers a webhook. Attach it to buckets by name or id. It is not available in a sandbox: sandboxes send nothing, neither webhooks nor mail. The URL must name a public server by hostname, on port 80, 443, 8080 or 8443; IP addresses, local and reserved names (localhost, .local, .internal, .home.arpa…), wildcard-DNS services and credentials in the URL are refused, when the destination is saved and again before each delivery. When a capture in that bucket is applied (by policy or by approval), it is POSTed:

{
  "version": 1,
  "event": "capture.applied",
  "sent_at": "2026-09-23T18:04:11.201Z",
  "tenant_id": "…",
  "raw": { "mode": "url", "url": "https://api.emailimport.com/raw/<message>?t=…&e=…&s=…", "expires_at": "…", "content_type": "message/rfc822" },
  "retention": "mximp deletes this message once every destination has received it; fetch the original now if you want it.",
  "capture": { "id": "…", "bucket": "customer-orders", "status": "applied", "fields": { "order_number": "A10234", "total": 86.5 }, "confidence": { "order_number": 1, "total": 1 }, "created_at": "…" },
  "message": { "id": "…", "from": "noreply@shop.example", "subject": "New order #A10234", "to": "orders@…", "received_at": "…", "auth": { "spf": "pass", "dkim": "pass", "dmarc": "pass" }, "flags": [] }
}

Headers: X-Mximp-Delivery (a unique id), X-Mximp-Event, and when the destination has a secret, X-Mximp-Signature: sha256=<hex HMAC-SHA256 of the raw body>. Verify the signature before trusting the body. raw is the original, the way the destination asked for it: url (default) is a signed link fetchable without a key for thirty minutes; inline is { "mode": "inline", "base64": "…" }; none omits it. An unrouted message delivered to the tenant's unrouted_destination arrives as event: "message.unrouted" with capture.bucket: "unrouted" and no fields. sent_at is inside the signed body and changes on every attempt: refuse a delivery much older than now, or older than the last one you stored for that capture, and a replayed old delivery cannot overwrite a newer one.

Delivery is one attempt, with the outcome (status code or error) recorded on the capture under deliveries; deliver_capture tries again on request. The payload carries a version; a change to its shape bumps it.

Email forward

An email destination forwards nothing until whoever reads that mailbox has confirmed it: add_destination mails a six-digit code to the address, confirm_destination takes it (24 hours; resend_destination_code mails a fresh one). The account's own confirmed address needs no code. Until confirmed, the destination's mail counts as undelivered and the message page says why.

add_destination with kind: "email" and to forwards each applied capture as mail from notify@mail.emailimport.com: a short body with the bucket, sender and field values, the original message attached as original.eml (message/rfc822) and the capture as capture.json. Sent from the platform's domain, not as the original sender, so the receiving side's DMARC is clean; the original inside the attachment still carries its own headers and authentication results. An original over 4.5 MB is not attached (the body says so; get_message has it while retained). Delivery is recorded like a webhook's, and the message is deleted after it like any other.

Undelivered

An applied capture no destination has received yet — the bucket has none, or every delivery failed — is undelivered: retained, listed by list_captures with delivery=undelivered, counted by get_tenant under undelivered with the tenant's cap (undelivered_cap, default 100) and an alarm to the tenant's devices once a day when the cap is passed or the oldest is a day old. deliver_capture tries again; delete_message discards one.

Changing a destination

update_destination changes a destination in place (url, secret, enabled, view_url), keeping its id and the buckets attached to it. Rotate a secret by setting it here and on the receiving side together. view_url is a page a person can open to see what the destination received, such as the receiving system's dashboard; the app links each bucket's destinations to it. mximp never fetches it.

Events

Every state change is an event: message.received, message.flagged, test.promoted, test.retired, capture.applied, capture.task, capture.field_set, task.created, task.resolved, bucket.created, bucket.updated, destination.added, delivery.succeeded, delivery.failed, message.reprocessed, policy.updated. Each carries its actor and a small payload.

list_events returns newest first. To catch up from a point you have seen, pass after=<event id> and you get the events since, oldest first. An agent that wakes up periodically can use this as its inbox.

This page as Markdown.