---
title: "Connect a Gmail inbox"
method: POST
path: "/mailboxes/connections"
tags: ["Mailboxes"]
---

# Connect a Gmail inbox

`POST /mailboxes/connections`

## Request

- Base URL: `https://api.mobilerun.ai`
- URL: `https://api.mobilerun.ai/mailboxes/connections`
- Auth: HTTP bearer

Links the caller’s Gmail account. Replaying the same Idempotency-Key returns the same mailbox. When Gmail is already active, redirectUrl is null and the mailbox is usable immediately.

## Headers

- `idempotency-key` string: Idempotency-Key: 1-255 printable ASCII characters. Same key with a different request body is a 422 idempotency_key_reused. A retryable in-flight duplicate is a 409 with Retry-After and x-should-retry: true; a terminal duplicate is a 409 with x-should-retry: false. A replay returns the current resource state with Idempotent-Replayed: true.

## Request body

- CreateMailboxConnectionRequest
  - `provider` 'gmail', required
  - `label` string
  - `bindingHash` string: sha256 hex of the browser-held connect binding secret.

## Response `200`

Gmail mailbox link

- MailboxConnection
  - `connectionId` string, uuid, required
  - `mailboxId` string, uuid, required
  - `redirectUrl` string, nullable, required
  - `status` 'pending' | 'active' | 'expired' | 'removed', required
  - `address` string, nullable, required

## Other responses

- `400`: The Idempotency-Key header is malformed
- `401`: Unauthorized
- `409`: Gmail already connected, or the mailbox backend rejected the request
- `422`: The Idempotency-Key was reused with a different request
- `429`: Mailbox backend rate limited
- `500`: Internal Server Error
- `503`: Mailboxes disabled or temporarily unavailable

## Changes

- **2026-10-21** `559a12449213`: 14 warning
  - added the new `integration_forbidden` enum value to the `anyOf[#/components/schemas/MailboxApiErrorEnvelope]/code` response property for the response status `400`
  - added the new `integration_forbidden` enum value to the `anyOf[#/components/schemas/MailboxApiErrorEnvelope]/code` response property for the response status `422`
  - added the new `integration_forbidden` enum value to the `anyOf[#/components/schemas/MailboxErrorBody]/code` response property for the response status `400`
  - added the new `integration_forbidden` enum value to the `anyOf[#/components/schemas/MailboxErrorBody]/code` response property for the response status `422`
  - …10 more
- **2026-10-16** `4ad548c528a8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/droidrun/apis/droidrun-cloud/changes/mailboxes/connections/post.md)

---

[API](https://skmtc.dev/droidrun/apis/droidrun-cloud.md) - [All operations](https://skmtc.dev/droidrun/apis/droidrun-cloud/llms.txt) - [OpenAPI document](https://skmtc.dev/droidrun/apis/droidrun-cloud/revisions/1cc95586c933?raw)