company logo

Help center

Go to Manyreach
All collectionsAPI & IntegrationsConnect Google Workspace & Microsoft 365 mailboxes via API (bulk OAuth, no passwords)

Connect Google Workspace & Microsoft 365 mailboxes via API (bulk OAuth, no passwords)

Connect up to 200 Google Workspace or Microsoft 365 mailboxes to a Manyreach workspace with the API and OAuth sign-in links. No passwords or app passwords.

Connect Google Workspace and Microsoft 365 mailboxes to a customer's Manyreach workspace in bulk through the Manyreach API, using OAuth sign-in links instead of passwords or app passwords. This guide is for done-for-you mailbox providers, email infrastructure resellers and agencies that set up cold email mailboxes for their clients.

How it works

  1. A Google Workspace or Microsoft 365 admin allows the Manyreach app once per domain or tenant.

  2. You create sign-in sessions for up to 200 mailboxes in one API call.

  3. You open each sign-in link as that mailbox. The mailbox is connected as a sender, with tokens instead of a password.

  4. You poll the sessions until each one is Connected, Failed or Expired.

Before you start

  • API key: the customer creates an API key in their Manyreach account and shares it with you. Every call sends it in the X-API-Key header.

  • Sender limit: every connected mailbox counts toward the customer's plan sender limit. Mailboxes over the limit come back as Failed with the reason.

  • API reference: Manyreach API v2 documentation, section "Done-for-you provider integration".

Step 1. Google Workspace: trust the Manyreach app

Do this once per Google Workspace, before the first sign-in. If you skip it, Google shows "Access blocked" and never returns to Manyreach, so the session stays Pending until it expires.

  1. Sign in to the Google Admin console as a super admin.

  2. Go to Security → Access and data control → API controls → Manage third-party app access, and click Configure new app.

  3. Search for the Manyreach client ID 23688329945-8lisrrrsg5q22b3kiikm27n792nf9qkc.apps.googleusercontent.com and select the Manyreach app. The same ID is returned as clientId on every session.

  4. Choose all users (or the organizational unit that holds the mailboxes), mark the app as Trusted, and click Finish.

Screenshots of these steps: Connecting Google Workspace accounts to Manyreach using OAuth.

Step 2. Microsoft 365: enable SMTP and IMAP, allow consent

  • Authenticated SMTP and IMAP: turn both on for every mailbox in the Microsoft 365 admin center (Active users → user → Mail → Manage email apps). Without them the mailbox connects but can't send, and it gets disconnected later. See How to enable IMAP and Authenticated SMTP in Microsoft 365.

  • Consent: the tenant must allow users to consent to the Manyreach app (client ID 56fe48ec-6d11-4c16-8471-353196c3f401), or a Global Administrator grants consent for the whole tenant once. Until then, sign-in shows "Need admin approval".

Step 3. Create sign-in sessions in bulk

Call POST /api/v2/oauth/sessions/bulk with the provider (Google or Microsoft), the daily sending limit and up to 200 mailboxes. Optional fields: warmup, folder and expiresInMinutes. For a single mailbox, use POST /api/v2/oauth/sessions.

http
POST https://app.manyreach.com/api/v2/oauth/sessions/bulk
X-API-Key: YOUR_CUSTOMER_API_KEY
Content-Type: application/json

{
  "provider": "Google",
  "dailyLimit": 25,
  "warmup": true,
  "sessions": [
    { "email": "[email protected]", "fromName": "Anna Smith" },
    { "email": "[email protected]", "fromName": "Mark Lee" }
  ]
}

The response has a batchId and one item per mailbox, each with a sessionId, a sign-in link (authUrl) and the clientId the link uses:

JSON
{
  "batchId": "…",
  "submitted": 2, "pending": 2, "failed": 0,
  "items": [
    { "sessionId": "…", "email": "[email protected]", "status": "Pending",
      "authUrl": "https://…", "clientId": "23688329945-….apps.googleusercontent.com" }
  ]
}

Step 4. Sign in and track progress

  1. Open each authUrl and sign in as that mailbox. No Manyreach login is needed. When the page says the mailbox is connected, it's a sender in the customer's workspace.

  2. Poll GET /api/v2/oauth/sessions?batchId=… every 15 to 30 seconds. Each session is Pending, Connected (with senderId), Failed (with error) or Expired.

How sessions behave

  • Single use: each link works once and only for the mailbox it was created for. Signing in with a different mailbox doesn't connect it, and you can retry the same link.

  • Expiry: links are valid for 72 hours by default. Set expiresInMinutes between 10 minutes and 7 days.

  • Already connected: if the mailbox is already an OAuth sender in that workspace, the session renews its tokens instead of adding a duplicate.

  • Keep links private: anyone who can sign in as the mailbox can complete a link, so don't publish them.

FAQ

Do I need the mailbox passwords or app passwords?

No. The mailbox signs in with Google or Microsoft, and Manyreach stores OAuth tokens. You never send a password to Manyreach.

Can I connect mailboxes in bulk without the customer logging in to Manyreach?

Yes. The API connects up to 200 mailboxes per call with the customer's API key. Only the sign-in for each mailbox is needed.

A session stays Pending after sign-in. Why?

Usually the Google Workspace admin hasn't trusted the Manyreach app yet (step 1), or the Microsoft 365 tenant needs admin consent (step 2). Fix the setting and open the same link again while it's still valid.

A session is Failed. What do I do?

Read its error. Common reasons: the mailbox is already a sender in another Manyreach account, the workspace reached its sender limit, or a newer session for the same mailbox replaced it. Fix the cause and create a new session.

Can I connect mailboxes to several customers' workspaces?

Yes. Use each customer's own API key. Mailboxes connect to the workspace that owns the key and count toward that workspace's sender limit.

When to contact support

Contact support if a mailbox keeps failing with the same error after you fixed the setting. Include the customer's account email, the session ID and the mailbox address.

Did this answer your question?
😞
😐
😁