---
title: "Connect an inbox by forwarding"
method: POST
path: "/api/emails/connect/forwarding"
tags: ["Email"]
---

# Connect an inbox by forwarding

`POST /api/emails/connect/forwarding`

## Request

- Base URL: `https://domani.run`
- URL: `https://domani.run/api/emails/connect/forwarding`
- Auth: HTTP bearer

Creates a connected mailbox at the inbox's own address and answers with a forwarding address on the platform's forwarding domain, with the steps for Gmail, Outlook and other providers. Add a forwarding rule at the provider; what arrives at that address is unwrapped (original sender, date, subject) and stored under the connected mailbox. Gmail asks the forwarding address to confirm: the code and the link appear on the connection. The first mail that comes back, or a probe (`POST /api/emails/{address}/connector/verify`), makes the connection active. Only new mail arrives this way; older mail cannot be imported. Requires `email:write`. The forwarding domain must be configured on the server.

## Request body

- object
  - `address` string, required: The inbox to connect, for example someone@gmail.com
  - `workspace_id` string: Workspace the mailbox belongs to; your personal workspace by default

## Response `200`

The forwarding address and the steps

- object
  - `address` string, required
  - `mailbox_id` string, required
  - `status` 'pending' | 'active', required
  - `forwarding_address` string, required
  - `instructions` object, required
    - `gmail` string[]
    - `outlook` string[]
    - `generic` string[]
  - `guide` ForwardingGuide: The guide of a forwarding connection: the provider the inbox lives at (from the address or its MX), the page where the rule is set, the steps in plain words, whether a confirmation comes back (Gmail's code and link, captured on the connection), and the provider's limits.
    - `provider` 'gmail' | 'google_workspace' | 'outlook' | 'microsoft365' | 'fastmail' | 'proton' | 'icloud' | 'yahoo' | 'generic', required
    - `name` string, required
    - `settings_url` string, nullable, required: The settings page where the forwarding rule is created, when the provider has a stable one
    - `confirmation` 'code_or_link' | 'none', required: code_or_link when the provider sends a confirmation the platform captures (Google)
    - `limits` string[], required
    - `steps` string[], required

## Other responses

- `400`: Invalid address
- `401`: Missing or invalid API key
- `409`: The address is a mailbox of another account, or connected another way
- `429`: Rate limit exceeded - wait and retry
- `503`: The forwarding domain is not configured

---

[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)