---
title: "Set the email webhook"
method: PUT
path: "/v1/mailboxes/{mailbox_id}/email/webhook"
tags: ["Email settings"]
---

# Set the email webhook

`PUT /v1/mailboxes/{mailbox_id}/email/webhook`

## Request

- Base URL: `https://api.revdoku.com`
- URL: `https://api.revdoku.com/v1/mailboxes/{mailbox_id}/email/webhook`
- Auth: HTTP bearer

Requires mailbox-admin permission and a public HTTPS URL. A new URL or rotate_secret=true creates a new signing secret, returns it once and cancels pending deliveries. The same URL without rotate_secret returns the webhook without a secret.

## Path parameters

- `mailbox_id` string, required

## Request body

- object
  - `webhook_url` string, uri, required
  - `rotate_secret` boolean
  - `account_id` string: Select another granted account for this request.
  - `reason` string, nullable: Optional purpose for this action. AI agents should explain intentional reads and changes when known; omit when unknown. Do not include secrets, file contents, or transcripts.

## Response `200`

Success

- object
  - `success` true, required
  - `data` object, required
    - `webhook` WebhookWithSecret, required
      - `url` string, uri, required
      - `event` 'email.received', required
      - `signing_secret` string: Returned once, when this request issues a secret: a new URL or rotate_secret=true. Store it to verify signatures.

## Other responses

- `default`: Request failed. See error.code. Any 429 or 503 response with Retry-After (for example 503 EMAIL_LABELING_PENDING or 503 EMAIL_INDEX_BUILDING): wait that many seconds, then try the read again. 429 EMAIL_SEND_RATE_LIMITED has no Retry-After. Never retry EMAIL_LOOP_DETECTED.

---

[API](https://skmtc.dev/revdoku/apis/revdoku-api.md) · [All operations](https://skmtc.dev/revdoku/apis/revdoku-api/llms.txt) · [OpenAPI document](https://skmtc.dev/revdoku/apis/revdoku-api/revisions/3ff4e2540a8b?raw)