Email

Set mailbox webhook

Configure the HTTPS destination for HMAC-signed mailbox events: inbound mail by default, plus (opt-in via events) the delivery verdict on mail sent FROM the mailbox - a bounce reaches the sender seconds after the send was accepted, instead of living only in the message trail. Live inbound deliveries are stored durably, attempted immediately, and retried up to three times. Each attempt includes X-Domani-Delivery-Attempt starting at 1. Optional Authorization or X-API-Key values are encrypted and never returned; human operators should submit them outside model context through the CLI environment-variable options.

put/api/emails/{address}/webhook

Request

  • Base URL: https://domani.run
  • URL: https://domani.run/api/emails/{address}/webhook
  • Auth: HTTP bearer

Path parameters

addressstring required

Mailbox email address (URL-encoded)

Request body

urlstring required

HTTPS webhook URL

eventsstring[]

Events to push (assistant.item.delegated and assistant.item.recalled tell an agent that the owner handed it a Today item or took it back; the webhook of every mailbox the agent operates receives them). Omitted keeps the current subscription (inbound only for a new webhook). Delivery verdicts on mail sent FROM the mailbox are opt-in and arrive at the same URL with the same signature: {event, mailbox, email, message: {id, message_id, to, subject, status, detail}}.

headersobject

Optional encrypted auth headers. Only Authorization and X-API-Key are accepted; send {} to clear. Do not pass values through model context; the CLI supports --authorization-env and --api-key-env.

Response

Webhook set

addressstring
webhook_urlstring
signing_secretstring
has_webhookboolean
eventsstring[]

Events this webhook carries: email.received, any delivery verdict on outbound mail (email.delivered, email.bounced, email.failed, email.suppressed, email.complained, email.delayed) and the agent hand-over notices (assistant.item.delegated, assistant.item.recalled); empty without a webhook

header_namesstring[]

Configured auth header names; values are never returned

hintstring

Changes

No recorded changes to this operation across all 2 revisions of this API.