Skip to content
AI Inbx
Esc
↑↓navigate↵open⌘Jpreview

Create a mailbox connection URL

Creates a single-use, short-lived URL that walks a customer through authorizing their Gmail or Outlook mailbox. Redirect them to it rather than emailing it. Pass ref — your own identifier — and metadata for anything else you want kept with the mailbox; both are stored on it and carried on every mailbox.* webhook. On a reconnect each replaces what the mailbox had, and one left out leaves it alone. The mailbox.connected webhook — not the browser returning to return_to — is the authoritative signal that the mailbox is live. return_to may be any URL here, since the request is authenticated; a connect link opened from a browser is held to the app’s return_urls instead. space_id files the mailbox in a space; the returned URL carries it, so a platform mints one link per customer server-side rather than handing out the bare hosted link. A workspace with no plan fails with 402 plan_required. A mailbox counts against the plan’s mailboxes, but which one it will be is only known once the person has authorized: with none left, a mailbox the workspace does not already hold is refused then, and the refusal is reported in error on return_to. Reconnecting one that is active or needs_reauth takes nothing new.

POST/mailboxes/connect
Authorization
AuthorizationBearer token (API key) · headerrequired

Pass an AI Inbx API key as a Bearer token.

Header parameters
AIInbx-Workspacestring

Workspace id from GET /workspaces, for an OAuth token that reaches several.

min length 1
Request body
requiredapplication/json
providerstringrequired

google for Gmail, microsoft for Outlook.

Allowed:googlemicrosoft
app_idstring

Your own OAuth app to connect through, so consent shows your product's name.

matches ^[a-z]+_[0-9a-f]{32}$
space_idstring

Which space a created resource goes in. Omitted, the workspace itself.

matches ^[a-z]+_[0-9a-f]{32}$
return_tostring<uri>required

Where the person is sent once they have authorized.

refstring

Your own identifier for whoever the mailbox belongs to. Kept on the mailbox and carried on every mailbox.* event.

min length 1 · max length 200
metadataobject

Your own key-value pairs, stored and given back as they are. Up to 50 keys; a key is 1–40 characters, a value up to 500. Written whole: what you send replaces what was there.

regionstring

The region the mailbox's mail is handled in.

Allowed:eu-central-1us-east-1
backfill_daysinteger

Days of existing mail to import, up to 90.

min 0 · max 90
Responses
201

A one-time connection URL was created.

urlstring<uri>required
400

The request is invalid.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
401

The API key is missing or invalid.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
402

The workspace has no plan (plan_required), or its plan's allowance is used up (allowance_reached).

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
403

The API key or token does not have the required scope, or the token is connected as an inbox and the operation is not one an inbox may use.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
404

The requested resource does not exist.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
409

The request conflicts with the resource's current state.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
413

The request body or attachments are too large.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
415

The request body is not JSON.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
422

The request body failed validation.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
429

The organisation's request budget is spent (too_many_requests), or an upstream mail provider is throttling (rate_limited).

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
500

An internal error occurred.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
502

An upstream mail provider failed.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
503

The service is temporarily unavailable.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
Request
import AIInbx from "aiinbx"

const aiinbx = new AIInbx()

const response = await aiinbx.mailboxes.connect({
  provider: "google",
  app_id: "app_0192a3b4c5d67890abcdef1234567890",
  return_to: "https://app.example.com/settings/email",
  ref: "user_4821",
})
Response
{
  "url": "http://example.com"
}