---
title: "Set mailbox webhook"
method: PUT
path: "/api/emails/{address}/webhook"
tags: ["Email"]
---

# Set mailbox webhook

`PUT /api/emails/{address}/webhook`

## Request

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

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.

## Path parameters

- `address` string, required

## Request body

- object
  - `url` string, required: HTTPS webhook URL
  - `events` string[]: 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}}.
  - `headers` object: 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 `200`

Webhook set

- object
  - `address` string
  - `webhook_url` string
  - `signing_secret` string
  - `has_webhook` boolean
  - `events` string[]: 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_names` string[]: Configured auth header names; values are never returned
  - `hint` string

---

[API](https://skmtc.dev/domani/apis/domani-run-api.md) · [All operations](https://skmtc.dev/domani/apis/domani-run-api/llms.txt) · [OpenAPI document](https://skmtc.dev/domani/apis/domani-run-api/revisions/7679f8159533?raw)