Skip to Content

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.

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 in the API reference.

Example

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

Arguments

ArgumentTypeDescription
mailboxIdstringMailbox ULID identifier. The path's {mailboxId}.
bodyMessageWebhookBodyThe 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).

Answer

Awaited, it is the API's JSON, MessageWebhook. It is an ApiPromise: .withResponse() gives the same with the Response it came in, for its headers.

Errors

StatusWhat it means
400validation_failed (the URL refused), or webhook_format_unavailable (format reference on a deployment that mints no capability URLs)
401unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a WWW-Authenticate: Bearer challenge
404Mailbox not found or not accessible to this principal
409account_required: the mailbox has no owning account
413too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing
503temporary_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: 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, MessageWebhookBody.