# mailboxes.setMessageWebhook

Create or replace the mailbox's message webhook.

Every message that lands in this mailbox is POSTed here (the incoming-email payload, its signing and retries), however it got there: any of its addresses, a pattern or catch-all route, a group, a forward or redirect into it, a delivery-status notice or a platform notice; and whether the mailbox then keeps it, files it, or discards it (a Sieve discard, or discardIncoming on GET/PUT /mailboxes/\{mailboxId\}/filtering). Not the mailbox's own writes (its Sent copies, drafts, APPEND and imports, POP3 pickups), and not mail the mailbox refused (a blocked sender, a receive hold). A webhook tap on one of its addresses (PUT /routes/\{address\}) is separate: with both, each POSTs. Deleting the mailbox stops the POSTs, including ones already queued, and restoring it brings it back without its webhook. Omit `secret` to keep the stored one, pass a string to rotate it, null to clear it; omit `format` to keep it. Only an account key or system key may set it.

```ts
openemail.mailboxes.setMessageWebhook(
  mailboxId: string,
  body: MessageWebhookBody,
  options?: CallOptions,
): ApiPromise<MessageWebhook>
```

It calls `PUT /mailboxes/{mailboxId}/message-webhook`: [Create or replace the mailbox's message webhook](/docs/api/mailboxes/put_MailboxMessageWebhookSet) in the API reference.

## Example

```ts
const messageWebhook = await openemail.mailboxes.setMessageWebhook(mailboxId, { url: 'https://example.com/hook' })
```

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `mailboxId` | `string` | Mailbox ULID identifier. The path's `{mailboxId}`. |
| `body` | [`MessageWebhookBody`](/docs/sdks/typescript/types/message-webhook-body) | The request's body. |

## Options

It takes no options of its own. Every call also takes `signal`, `timeout`, `retry` and `headers`, which say how that one call is sent ([call options](/docs/sdks/typescript/calling-methods#call-options)).

## Answer

Awaited, it is the API's JSON, [`MessageWebhook`](/docs/sdks/typescript/types/message-webhook). It is an [`ApiPromise`](/docs/sdks/typescript/responses): `.withResponse()` gives the same with the `Response` it came in, for its headers.

## Errors

| Status | What it means |
| --- | --- |
| `400` | validation_failed (the URL refused), or webhook_format_unavailable (format reference on a deployment that mints no capability URLs) |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `404` | Mailbox not found or not accessible to this principal |
| `409` | account_required: the mailbox has no owning account |
| `413` | too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing |
| `503` | temporary_failure: the mailbox's creation (POST /identities with messageWebhook) is still installing its webhook; retry after Retry-After. temporary_failure: the mailbox or account is in transition while its store is being adopted; retry after Retry-After |

A failed call rejects with a [`RequestError`](/docs/sdks/typescript/errors): its `status`, and its `code`, the API's `error`. Decide on the code: one status covers several.

## Types

It names these types of the API, each on a page of its own: [`MessageWebhook`](/docs/sdks/typescript/types/message-webhook), [`MessageWebhookBody`](/docs/sdks/typescript/types/message-webhook-body).
