---
# @generated by sylphx-gen 0.1.0 from contracts@f43687e14b51721de401af0b4dfdca44ad768a0c80ebc87a5f5fd6b3ff19f7d7. Do not edit.
title: "Mailbox connect links"
description: "The `mailbox_connect_links` collection of Sylphx Notify: A Mailbox Connect Link is a hosted page that a platform customer's server mints with its own server key for one end user, who approves the provider's consent there."
type: reference
product: email
summary: "A Mailbox Connect Link is a hosted page that a platform customer's server mints with its own server key for one end user, who approves the…"
updated: 2026-09-28
order: 900
---

A Mailbox Connect Link is a hosted page that a platform customer's server mints with its own server key for one end user, who approves the provider's consent there. The mailbox it connects lives in the customer's environment, and the end user signs in to nothing of Sylphx and sees no Sylphx name. It is single use and expires (the Stripe Account Link model): pressing Continue on the page claims it, so a link preview's fetch does not; a claimed or expired link sends the end user to `refresh_url`, where the customer's server mints a new one.

**Service** Sylphx Notify · **Resource type** `notify.sylphx.com/MailboxConnectLink` · **Name pattern** `orgs/{org}/projects/{project}/envs/{env}/mailbox_connect_links/{mailbox_connect_link}` · **Shape** `record`

## Fields

| Field | Type | What it is |
| --- | --- | --- |
| `name` | `string` | `orgs/{org}/projects/{project}/envs/{env}/mailbox_connect_links/{mailbox_connect_link}`. |
| `uid` | `string` | `mcl_<cell><ulid>`; never reused. Output only. |
| `meta` | `ResourceMeta` | Resource metadata; labels may carry the customer's own end-user id. |
| `provider` | `MailboxOauthProvider` | The provider whose consent the page opens; the environment needs that provider's Mailbox OAuth App. Required. One of `google`, `microsoft`. |
| `mailbox` | `string` | The mailbox to reconnect, keeping its id and feed; it must be signed in as the same address. Empty creates a new connected mailbox. |
| `mailbox_id` | `string` | The id of the new mailbox; the server assigns one when empty. |
| `display_name` | `string` | The From display name of the new mailbox. |
| `backfill_start_time` | `timestamp` | The new mailbox reads mail received on or after this day on its first poll. |
| `login_hint` | `string` | The address to suggest on the consent screen (`login_hint`); the mailbox takes the address the provider confirms, whatever this says. |
| `return_url` | `string` | Where the end user lands when done, HTTPS, with `connect_link={id}` and `result=connected` or `result=failed` added to the query. The query proves nothing: read the link back with your key for the outcome. Required. |
| `refresh_url` | `string` | Where a claimed or expired link sends the end user, HTTPS; your server mints a new link there. Empty shows a page saying the link has expired. |
| `ttl` | `duration` | How long the link stays open; default 1 hour, at most 7 days. |
| `url` | `string` | The link to hand the end user. It is a bearer secret: only the create call returns it, and only its hash is stored. Output only. Never returned again. |
| `state` | `MailboxConnectLinkState` | The lifecycle state. Output only. One of `pending`, `claimed`, `connected`, `failed`, `expired`. |
| `expire_time` | `timestamp` | When it expires. Output only. |
| `complete_time` | `timestamp` | When the end user finished, connected or failed. Output only. |
| `connected_mailbox` | `string` | The mailbox it connected or reconnected. Output only. |
| `address` | `string` | The address the provider confirmed. Output only. |
| `error_code` | `string` | Why it failed: `consent_denied`, `scope_missing` (the end user unticked a scope), `address_mismatch` (a reconnect signed in as another address), `address_in_use` (another mailbox of the environment has the address), `plan_limit_reached`, or `provider_error`. Output only. |

## Methods

Every method of the collection, in the registry's order, with the scope it
needs. The full request, response and examples are one link away.

| Method | Call | What it does |
| --- | --- | --- |
| `GET` | [`get`](/docs/api/mailbox_connect_links#get) | Gets a mailbox connect link. |
| `GET` | [`list`](/docs/api/mailbox_connect_links#list) | Lists mailbox connect links. |
| `POST` | [`create`](/docs/api/mailbox_connect_links#create) | Mints a mailbox connect link for one end user; the response carries its `url`, which no later call returns. |

## get

Gets a mailbox connect link.

`GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/mailbox_connect_links/mailbox-connect-link` · scope `notify:read` · effect `read` · [Request, response and examples](/docs/api/mailbox_connect_links/get)

## list

Lists mailbox connect links.

`GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/mailbox_connect_links` · scope `notify:read` · effect `read` · paginated · [Request, response and examples](/docs/api/mailbox_connect_links/list)

## create

Mints a mailbox connect link for one end user; the response carries its `url`, which no later call returns.

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/mailbox_connect_links` · scope `notify:write` · effect `write` · [Request, response and examples](/docs/api/mailbox_connect_links/create)