Connect a Microsoft Mailbox

Use this flow to connect a single Microsoft mailbox to TrulyInbox with the API. This is the mailbox-level OAuth flow for connecting one account without a workspace-wide admin consent workflow.

This is different from bulk-connecting a Microsoft 365 workspace, which connects an entire tenant through admin consent. Use this guide when you want to connect one mailbox instead of a full workspace.

For any questions or help, contact us at support@trulyinbox.com or book a meeting.

How identity is verified

When you request the consent link, pass the mailbox address you want to connect in the email parameter. The connection only succeeds if the Microsoft account you sign in with resolves to that exact address. If you sign in with a different mailbox, Microsoft blocks the flow before the account is connected.

This keeps the trust model simple: there is no verification endpoint to host and no follow-up vouching step after sign-in, because Microsoft's own login already confirms the mailbox belongs to the right account. This also means the email value has to be correct.

The flow

1. Call the consent-url endpoint with the mailbox address you want to connect.
2. Open the URL returned in the response.
3. Sign in to Microsoft and approve access.
4. Microsoft redirects back to TrulyInbox. TrulyInbox exchanges the authorization code for tokens, confirms the mailbox matches the email value you declared, and connects the account.
5. The browser lands on the plain TrulyInbox homepage, where you'll see a message confirming whether the mailbox connected successfully or, if not, why.

Step 1: Request the consent link

Pass the Microsoft mailbox address you want to connect as the email query parameter. This is the mailbox the connection is pinned to — the flow only succeeds if the Microsoft account you sign in with resolves to this exact address.

The returned link is single-use and expires in 30 minutes. Generate it right before you want to log in, and do not pre-generate or store it for later use.

curl -X GET "https://lupus-edge.trulyinbox.com/v1/email-accounts/microsoft/consent-url?email=alice%40company.com" \
  -H "X-Api-Key: YOUR_API_KEY"

{
  "url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=...&redirect_uri=...&state=...",
  "expiresAt": "2026-08-14T13:00:00.000Z"
}

Step 2: Open the sign-in URL

Open the url from the response in the browser. There is nothing else to do here — Microsoft's login screen is already prefilled with the email value you declared, which reduces the chance that you sign in to the wrong account.

Step 3: The result

Once the flow finishes, the browser lands on the plain TrulyInbox homepage, where you'll see a message telling you the mailbox connected successfully, or why it didn't. There is no callback to your system at this point, and no follow-up API call is required for the account to be connected; it is already connected or not connected by the time the redirect happens.

If your integration needs to confirm the outcome on your side, check GET /v1/email-accounts and look for the mailbox address you declared. If it is not there a few seconds after the sign-in completes, treat it as a failed attempt and retry from Step 1.

Flow at a glance: Request consent link (declare expected email) → Redirect browser → Sign in to Microsoft → TrulyInbox verifies the mailbox matches, connects it, and shows you the outcome

Notes

• Re-requesting a consent link (Step 1) at any time is fine — each one is independent and single-use.
• If the mailbox is already connected under your account, TrulyInbox treats it as a token refresh on the existing connection rather than creating a duplicate.
• This flow does not require anything registered up front — unlike bulk connect, there is no separate admin-consent or domain-wide-delegation step, and no host or credentials to register with TrulyInbox.
• If warmup isn't running on the connected account, call Start Warmup to start it.