---
title: "Read the connection of a connected mailbox"
method: GET
path: "/api/emails/{address}/connector"
tags: ["Email"]
---

# Read the connection of a connected mailbox

`GET /api/emails/{address}/connector`

## Request

- Base URL: `https://domani.run`
- URL: `https://domani.run/api/emails/{address}/connector`
- Auth: HTTP bearer

Kind, status, the import bound, the sync phase (the import scan, then history), the import progress (scanned, copied, to analyse, analysed), the last sync and the last error. Requires `email:read`. The forwarding confirmation (Gmail's code and link) is authentication mail: without `email:auth_secrets` its code and url are null and it carries `redacted: true`. A mailbox-confined token finds only its own mailboxes (404 otherwise).

## Path parameters

- `address` string, required

## Response `200`

The connection

- MailboxConnection: The connection of a mailbox that lives elsewhere (Gmail, or any inbox by forwarding) and its import progress
  - `address` string, required
  - `mailbox_id` string, required
  - `kind` 'gmail' | 'graph' | 'forwarding' | 'imap' | 'jmap', required
  - `status` 'pending' | 'active' | 'error' | 'disconnected', required
  - `import_since` string, date-time, nullable: The bound of the first import: no mail received before it is copied
  - `phase` 'list' | 'history' | 'paused', required: list while the import scan pages through the mail after the bound, history once new mail follows the source's history
  - `paused_reason` string, nullable
  - `import_run` object, nullable: The current or last import run of this mailbox
    - `id` string
    - `status` 'running' | 'completed'
    - `since` string, date-time, nullable
    - `until` string, date-time, nullable
    - `listed` integer
    - `copied` integer
    - `to_analyse` integer
    - `analysed` integer
    - `listing_done` boolean
    - `started_at` string, date-time
  - `source_messages_total` integer, nullable: What the source reports for the whole inbox, for scale
  - `last_sync_at` string, date-time, nullable
  - `last_error` string, nullable
  - `backoff_until` string, date-time, nullable
  - `verified_at` string, date-time, nullable
  - `connected_at` string, date-time, required
  - `cost_cap_usd` number: The model spend allowed per import run, in USD
  - `access` 'read' | 'write', nullable: For a Gmail connection: what the grant allows; write means labels both ways and sending as the person
  - `forwarding` object, nullable: For a connection by forwarding: the forwarding address, what arrived, Gmail's confirmation, the probe, the steps
    - `address` string, nullable
    - `forwarded` integer
    - `last_forwarded_at` string, date-time, nullable
    - `confirmation` object, nullable: Gmail's forwarding confirmation, which is authentication mail: without email:auth_secrets, code and url are null and redacted is true
      - `code` string, nullable
      - `url` string, nullable
      - `received_at` string, date-time
      - `redacted` boolean: True when the code and link are withheld because the caller lacks email:auth_secrets
    - `probe` object, nullable
      - `sent_at` string, date-time
      - `returned_at` string, date-time, nullable
    - `instructions` object, nullable
      - `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

- `401`: Missing or invalid API key
- `404`: No connected mailbox at this address
- `429`: Rate limit exceeded - wait and retry

---

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