---
title: "Start connecting a Gmail inbox"
method: POST
path: "/api/emails/connect/gmail"
tags: ["Email"]
---

# Start connecting a Gmail inbox

`POST /api/emails/connect/gmail`

## Request

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

Returns the Google consent URL bound to your account and to the import bound. Open it in a browser; after consent the inbox becomes a connected mailbox at its own address, the mail received after the bound is imported (default: the last 24 hours), and new mail follows as it arrives. Never the whole inbox: widen later with `POST /api/emails/{address}/import`. Requires `email:write`. Google OAuth must be configured on the server.

## Request body

- object
  - `access` 'read' | 'write': read (the default) reads the inbox; write also lets the platform change labels and the read state and send as the person, for the effects of a standing delegation. Reconnect with write to widen a read-only grant.
  - `since` string, date-time: Import the mail received after this instant
  - `window` '24h' | '7d' | '30d' | '1y': A preset instead of since; default 24h
  - `workspace_id` string: Workspace the mailbox belongs to; your personal workspace by default
  - `login_hint` string: The Google account to preselect
  - `return_to` string: App path to send the browser to after consent

## Response `200`

The consent URL

- object
  - `auth_url` string, required
  - `state` string, required
  - `import_since` string, date-time, required
  - `expires_in` integer, required
  - `access` 'read' | 'write'

## Other responses

- `400`: Invalid since or window
- `401`: Missing or invalid API key
- `429`: Rate limit exceeded - wait and retry
- `503`: Google OAuth or the credential key 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)