Skip to Content

Add a forwarding destination.

Names an address and mails it an eight-character confirmation code, valid for 24 hours. The destination forwards nothing until the code is confirmed. Re-posting an address that already exists re-mails a fresh code rather than refusing, which is also how a destination the recipient revoked is re-proved.

openemail.forwarding.addDestination(
  mailboxId: string,
  body: ForwardingAddDestinationBody,
  options?: CallOptions,
): ApiPromise<ForwardingDestinationPending>

It calls POST /mailboxes/{mailboxId}/forwarding/destinations: Add a forwarding destination in the API reference.

Example

const forwardingDestinationPending = await openemail.forwarding.addDestination(mailboxId, { address: 'ada@example.com' })

Arguments

ArgumentTypeDescription
mailboxIdstringMailbox ULID identifier. The path's {mailboxId}.
bodyForwardingAddDestinationBodyThe 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, ForwardingDestinationPending. It is an ApiPromise: .withResponse() gives the same with the Response it came in, for its headers.

Errors

StatusWhat it means
400validation_failed; or destination_is_self / destination_loops / destination_chain_too_long when the address routes back to this mailbox; or destination_not_permitted when the account's allowlist refuses it; or destination_fans_out when the address is one we host that reaches more than one party (a group, alias, webhook or onward-forwarding route), which cannot consent to the confirmation code or hold the disable link
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
409too_many_destinations — the per-mailbox cap is reached; remove one first
413too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing
429resend_cooldown — a code was mailed to this address recently; or rate_limited, with Retry-After, when this mailbox's confirmation-mail budget is spent. The two are deliberately not distinguishable further: the budget is partly shared per destination address across the deployment
503forwarding_mail_unavailable — the confirmation could not be sent for a reason on the platform's side (the mail binding is unconfigured, or the sending service refused the message), so no pending row is stored and the request may be retried. A refusal that concerns the destination address itself is deliberately indistinguishable from a sent code. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)

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

ForwardingAddDestinationBody

/** The body of `forwarding.addDestination`. */
type ForwardingAddDestinationBody = {
  /** The address to forward to */
  address: string
}

It names these types of the API, each on a page of its own: ForwardingDestinationPending.