Mailboxes

Connect an existing Gmail or Outlook account over OAuth — from a hosted page, a plain link, or the API — keep it synced, and put your own brand on the consent screen.

A mailbox is an existing Gmail or Outlook account, connected once over OAuth. Its mail keeps flowing through Google or Microsoft exactly as before; AI Inbx syncs it, and can send and receive as that address.

That’s the difference from a domain, which needs DNS access and takes over mail for every address on it. A mailbox needs nothing but the account holder clicking approve, changes nothing about their existing setup, and covers one address.

Reach for it when the address already has an inbox somewhere — a rep’s work account, a founder’s inbox — and the mail should read as coming from that person.

Connecting a mailbox

Three ways in, ordered by how much of the flow you own. They all end the same way: the person approves at Google or Microsoft, the mailbox lands in your workspace, and mailbox.connected fires.

Hosted page

Every OAuth app of yours has a page at its connect_url — https://aiinbx.com/connect/<slug> — wearing your name, logo, accent and support address, with nothing of AI Inbx on it. Send people there, or put it in an email; it’s a permanent link, not a one-time one.

https://aiinbx.com/connect/acme?ref=user_8812

Brand the page from the app’s settings in the console, or through oauthApps.create — accent, tagline, support_email, logo_url.

Connect link

The same handoff with no page of ours in it. The person clicks a button on your site, lands on the consent screen, and comes back to a page of yours. Build the URL yourself; there’s nothing to call first:

https://aiinbx.com/connect/<slug>/start?return_to=<url>&ref=<id>

await aiinbx.oauthApps.update(app.id, {
  return_urls: [
    "https://app.example.com/settings/mailboxes",
    "http://localhost:3000/settings/mailboxes",
  ],
})

const connectUrl = new URL(`https://aiinbx.com/connect/acme/start`)
connectUrl.searchParams.set("return_to", "https://app.example.com/settings/mailboxes")
connectUrl.searchParams.set("ref", user.id)

<a href={connectUrl.href}>Connect your Gmail</a>

<a href="https://aiinbx.com/connect/acme/start?return_to=https%3A%2F%2Fapp.example.com%2Fsettings%2Fmailboxes&ref=user_8812">
  Connect your Gmail
</a>

if (event.type === "mailbox.connected") {
  await markMailboxReady(event.data.ref, event.data.mailbox_id)
  // `reconnected` is true when this replaced an existing authorization.
}

API

For when your server should decide — the region, how much history to import, or the shared AI Inbx app rather than your own. The URL it returns is single-use and short-lived: redirect to it, don’t email it.

const { url } = await aiinbx.mailboxes.connect({
  provider: "google",
  return_to: "https://app.example.com/settings/mailboxes",
  ref: "user_8812",
  backfill_days: 30,
})
// Send the customer to `url`.

The return carries the same query as a connect link, and the same rule applies: wait for mailbox.connected rather than trusting the redirect. A stale URL fails with expired_state. Creating connection URLs requires a full scope key.

space_id is the reason a platform uses this path: it is the only one of the three that can put the mailbox in a space. The hosted page and a connect link are opened with no credential, so they cannot take a space — anyone could file a mailbox into another customer’s. A mailbox lands in a space only through this call, which binds the space inside the encrypted OAuth state of the URL it returns. So a platform mints the connect URL server-side, per customer, and never hands out the bare hosted link.

Mailbox state

const mailbox = await aiinbx.mailboxes.retrieve("mbx_...")

console.log(mailbox.address, mailbox.state, mailbox.last_sync_at)

mailbox = client.mailboxes.retrieve("mbx_...")
print(mailbox["address"], mailbox["state"])

state_reason carries the provider’s explanation when there is one. Both transitions are also webhooks — mailbox.needs_reauth and mailbox.disconnected — which is the right place to trigger a re-authorization prompt rather than discovering it on the next failed send. The workspace’s owners and admins also get an email when a mailbox needs re-authorization, one per batch rather than per mailbox — each of them at the level they picked under Settings → Notifications.

Sending from a mailbox that isn’t active fails with 409 mailbox_inactive.

Syncing

Mail arrives on its own — Gmail through push notifications, Outlook through Graph subscriptions. sync forces a catch-up when you have a reason to think something was missed:

await aiinbx.mailboxes.sync("mbx_...") // 202, queued

client.mailboxes.sync("mbx_...")

curl -X POST https://api.aiinbx.com/api/v2/mailboxes/mbx_.../sync \
  -H "Authorization: Bearer $AI_INBX_API_KEY"

It returns 202 with { "status": "queued" } — the work happens in the background, and the messages surface as ordinary email.received events. It isn’t a way to poll for mail; it’s a repair tool.

Disconnecting

const mailbox = await aiinbx.mailboxes.disconnect("mbx_...")
console.log(mailbox.state) // "disconnected"

Sync stops and the stored credentials are dropped. Messages already received stay on their threads.

Your own OAuth app

By default the consent screen says AI Inbx. Register your own Google or Microsoft app and it says your product’s name instead — which is usually a requirement, not a preference, once you’re asking a business customer for mailbox access.

const app = await aiinbx.oauthApps.create({
  provider: "google",
  name: "Acme Assistant",
  slug: "acme",
  client_id: process.env.GOOGLE_CLIENT_ID!,
  client_secret: process.env.GOOGLE_CLIENT_SECRET!,
  tagline: "Let Acme handle your inbox",
  support_email: "support@acme.com",
  return_urls: ["https://app.acme.com/settings/mailboxes"],
})

console.log(app.redirect_uri) // register this with the provider
console.log(app.connect_url) // the hosted page; + "/start?return_to=…" is the connect link
console.log(app.push_endpoint) // Google only — the Pub/Sub push endpoint

slug is claimed globally; a taken one fails with 409 slug_taken. A workspace configured to require its own app returns shared_apps_disabled if you try to connect without an app_id.

Secrets can be rotated with oauthApps.update; the old value is replaced immediately, so update the provider first.

Domains or mailboxes?

Not a question of whose address it is — either one can be yours or your customer’s. A domain you add on a customer’s behalf, walking them through the DNS records, is an ordinary domain. What differs is what you need from them and what you get.

The deciding question is usually whether the address already receives mail somewhere. An address on a live Google Workspace or Microsoft 365 domain has an inbox already, and pointing the MX record at AI Inbx would take that over for the whole domain — connect the mailbox instead. A domain with nowhere for its mail to go yet, or a subdomain created for the purpose, is the domain case.

Plenty of products use both, and often both on behalf of the same customer: a subdomain for anything the product sends, connected mailboxes for anything written from a person’s own inbox.