Shared mailbox (OAuth) sending

Send from a real Gmail or Microsoft 365 shared mailbox — Sent folder, replies, and delegated permissions all handled by the provider.

Team sender addresses on their own (Team sender addresses) are perfect when you want talent@company.com to look like a real address to candidates and don't care where sends live afterwards. Every send goes through your verified email configuration, replies land wherever your Reply-To points, and there is no separate mailbox to manage.

Sometimes you want more. Specifically:

• Messages InsightHire sends should show up in the shared mailbox's own Sent folder so your team sees them in Gmail or Outlook.
• Replies should land in the shared mailbox's Inbox the same way replies from other channels do, with mailbox rules, categories, and delegated permissions all working normally.
• Team members with delegated access to the shared mailbox should be able to reply from their own client without your platform in the middle.

That's the Pro tier: a team sender can additionally be attached to an OAuth mailbox connection — Google Workspace or Microsoft 365 — so the send happens through the provider's API, not through your SMTP provider.

When to use each pattern

Most customers should start with team sender only. Attach a shared mailbox when your team explicitly wants Sent-folder mirroring or delegated replies from their own clients.

Requirements

• Your organization has an active, verified email configuration (SMTP or Resend).
• The domain of your intended sender address is DKIM-verified and SPF-verified — same requirement as any team sender.
• You have admin rights in InsightHire (the shared-mailbox picker is admin-only).
• The mailbox itself is provisioned in your provider (see the provider-specific sections below).
• One admin has connected the mailbox to InsightHire via OAuth. The "Connect a shared mailbox" button on the Team senders card (below) walks you through it — you no longer have to connect from your own recruiter profile first.

The one-click "Connect a shared mailbox" flow

The Team senders card has a Connect a shared mailbox button that packages the whole flow:

1. Click Connect a shared mailbox.
2. Pick the provider (Google Workspace or Microsoft 365) and type the shared address (talent@company.com).
3. Click Connect — you'll be redirected to Google or Microsoft to sign in.
   • Google: sign in as the shared account itself (talent@company.com). InsightHire refuses the connection if you sign in as a different account.
   • Microsoft 365: sign in as any user who has SendAs on the shared mailbox. The shared mailbox address you entered is used to target POST /users/{shared}/sendMail.
4. After consent, you land back on Email settings with an "Add sender" form pre-populated with the address and the connection already selected. Fill in the display name, hit Add sender, and you're done.

The provider-specific sections below are still worth reading — they cover the prerequisites you need in Google Workspace / Microsoft 365 before you start this flow.

Set up a Google Workspace shared mailbox

Google Workspace does not have a formal "shared mailbox" concept the way Microsoft 365 does. Two shapes are common:

• A licensed user account dedicated to a role (e.g. talent@company.com as a real Workspace user). Team members are granted Gmail delegation in the account's Gmail settings so they can read and reply from their own Gmail. This is the setup InsightHire integrates with.
• A Google Group used as an alias (talent@company.com forwarded to individual users). InsightHire cannot send as a group via API. Convert the alias to a licensed user account if you want provider-side send.

Steps

1. In Google Workspace, provision talent@company.com (or your intended shared address) as a licensed user account.
2. From that account's Gmail settings → Accounts and Import → Grant access to your account, add your team members so they can read and reply from their own Gmail.
3. In InsightHire, sign in as the team member who will do the OAuth grant and go to Configurations → Communications → Email settings → Connected mailboxes (or your recruiter profile's mailbox connection page).
4. Complete Google OAuth for the shared account. Grant the gmail.send scope.
5. Return to Team sender addresses. Add a sender:
   • Local part and Domain matching the shared address.
   • Send via connected shared mailbox — pick the Gmail connection you just made.
6. Save.

From now on, InsightHire messages sent from that team sender land in the shared account's Sent folder. Team members with Gmail delegation see them there and can reply from their own Gmail; replies land in the shared account's inbox as normal.

Set up a Microsoft 365 shared mailbox

Microsoft 365 does have a formal shared mailbox. It is not a licensed user — it's a mailbox resource with SendAs and Full access permissions granted to specific users.

Steps

1. In the Microsoft 365 admin center, provision talent@company.com as a shared mailbox.
2. Grant SendAs permission to the team members who will send from it. Full access is also useful so those team members can read the mailbox in Outlook.
3. Ensure the shared mailbox's address lives on a domain that is DKIM-verified and SPF-verified in InsightHire.
4. In InsightHire, sign in as one of the users who was granted SendAs, and complete Microsoft 365 OAuth (Mail.Send scope) for that user's own account. InsightHire does not OAuth the shared mailbox itself — Microsoft doesn't support that.
5. Return to Team sender addresses. Add a sender:
   • Local part and Domain matching the shared address.
   • Send via connected shared mailbox — pick the Microsoft 365 connection.
   • Microsoft SendAs address — enter the shared mailbox address. Defaults to the composed From address.
6. Save.

InsightHire calls Microsoft Graph's POST /users/{sharedAddress}/sendMail endpoint with the connected user's token. Graph writes the message directly into the shared mailbox's Sent Items. Replies from candidates go to the shared address and land in the shared mailbox's inbox natively.

Sender precedence at send time

When InsightHire is about to send a message, it resolves the effective sender in this order:

1. Explicit senderId passed by the caller (typically a template override).
2. The senderId stored on the associated email template.
3. Your organization's default team sender, if any.
4. Fall back to the org's configured From address (from the email configuration).

Once a team sender is picked, InsightHire re-verifies that the domain is still DKIM+SPF-verified. If yes, it uses that sender.

If the sender is attached to a shared mailbox connection, InsightHire additionally verifies:

• The connection is still active (token not revoked).
• The user who did the OAuth is still a current member of the organization.

If either check fails, InsightHire silently falls back to the SMTP path using the same From/Reply-To but going through your Resend/SMTP configuration instead of the OAuth mailbox. It never fails the send.

That fallback means you can revoke consent, remove the user, or the token can expire without breaking outbound mail — you just lose Sent-folder mirroring until the connection is restored.

Reply routing

• Team sender only — replies go to your Reply-To address. Set it to a shared inbox, a distribution list, or the sender address itself.
• With shared mailbox attached — the From address is the shared inbox; replies naturally land there. No Reply-To gymnastics needed.

Reply sync back onto the candidate timeline

Microsoft 365 only. If the connected mailbox was granted Mail.Read when the OAuth was consented, replies from candidates in threads InsightHire started are pulled back and appear on the candidate's timeline — same as replies to any other outbound. Details on the exact mechanism live in the mailbox-reply-sync service header.

• Google shared mailbox — InsightHire only has gmail.send and never reads Gmail, so there is no reply sync for Google.
• Microsoft SendAs shared mailbox — the connected user OAuthed their own mailbox, but replies land in the shared mailbox's inbox (candidates reply to the From address). InsightHire's reply-sync scans /users/{shared}/messages in that case, which requires the connected user to have Full Access on the shared mailbox in addition to SendAs. Granting SendAs alone lets you send but not read; reply-sync will silently skip until Full Access is added.

Stale-token banner and one-click reconnect

If the OAuth token for an attached shared mailbox dies — revoked in the provider's console, the user's password rotated, the refresh token expired — the sender row on the Team senders card shows a warning banner explaining the current state:

• "The shared mailbox this sender points at is no longer connected" — the connection row has been deleted (typically because the user who OAuthed it was removed from the org). Emails still go out via platform SMTP; you lose Sent-folder mirroring until you re-attach a fresh connection.
• "The OAuth token for talent@company.com was revoked or expired" — the connection is present but inactive. Emails fall back to SMTP.
• "Last provider error on talent@company.com: …" — the provider is rejecting sends. Details in the message.

Each banner has a Reconnect talent@company.com button that restarts the same connect flow for the same shared address. The user re-consents at Google / Microsoft, and the connection flips back to active on return.

Rate limits

• Team sender only uses your email configuration's rate limits and provider quotas (Resend, SMTP relay, etc.).
• With shared mailbox attached uses the mailbox connection's own daily counter (default 200/day, admin-configurable per connection). Gmail and Microsoft Graph have their own provider-side limits — check with your IT admin if you plan high volume.
• Each sender row on the settings card shows a quota chip — 47 / 200 today — pulled from the attached connection's counter. It flips to warn color at 80% and danger at 100%.

Send a test message

Every sender row on the Team senders card has a Send test button. For an OAuth-attached sender the test dispatches through the actual shared-mailbox path (Gmail messages.send or Graph POST /users/{shared}/sendMail), so the token, SendAs grant, and Sent-folder mirroring are all exercised end-to-end. The button reports back with Test sent via OAuth shared inbox when it worked, or the provider error text when it didn't — no candidate email needed to smoke-test a connection.

Audit and reporting

Every send is logged in email_logs with a resolvedSender block on its metadata. When a shared mailbox handled the send, the block includes dispatchedVia: 'oauth_mailbox', the provider (GOOGLE or MICROSOFT), the mailbox connection id, and the SendAs address if applicable. Reports and support tickets can use this to disambiguate which path a particular message went out on.

The Email Logs page (Configurations → Communications → Email settings → View email logs) has a filter chip row above the list — flip it to OAuth shared inbox to see only messages that were dispatched through this path, or Platform SMTP to see only the fallback path. Rows in the OAuth view also carry an inline "Gmail shared inbox" / "Microsoft 365 shared inbox" chip on their meta line.

Troubleshooting

The "Send via connected shared mailbox" picker is empty

Nobody has connected an OAuth mailbox for your org yet. Ask a team member to complete Gmail or Microsoft 365 OAuth from their own profile, then re-open Add sender.

"Selected mailbox connection is missing the send permission"

The OAuth grant did not include gmail.send (Google) or Mail.Send (Microsoft). Ask the person who connected to reconnect and grant the missing scope.

"Send-as address … is not on a verified domain"

Microsoft SendAs targets must live on a DKIM+SPF-verified domain in your organization. Verify that domain in Email settings → Domains first.

Sends from the shared mailbox show up in the connected user's Sent folder instead of the shared mailbox's Sent

That's Gmail's default behavior when you set up "Send mail as" instead of Gmail delegation, or when a Microsoft user sends from their own mailbox with a spoofed From. InsightHire routes through the shared mailbox directly (Google: OAuth the shared account itself; Microsoft: /users/{shared}/sendMail) so this shouldn't happen — if it does, verify you selected the correct connection in the sender's config.

Team members can't reply from their own client

• Google: grant them Gmail delegation on the shared account (Settings → Accounts and Import → Grant access).
• Microsoft 365: grant them SendAs on the shared mailbox (Exchange admin center → Recipients → Mailboxes → your shared mailbox → Delegation). Full access is also useful so they can read the mailbox in Outlook.

Enterprise tier — platform-owned application access

The Pro tier described above is per-user OAuth: one team member consents, and the platform sends as (or on behalf of) that account. Individual users, individual tokens, per-user rate limits.

The Enterprise tier flips that around. An IT admin runs a one-time authorization in their Workspace / Azure tenant, and InsightHire can then send as any user in the domain — without any user-level OAuth on our side. All setup is via cut-and-paste; there are no customer keys to upload and no customer JSON stored in our database.

Under the hood:

• Google Workspace: the platform ships one service account in our GCP project. Your Workspace super-admin adds our SA's OAuth client ID (shown in the setup card) to Admin console → Security → API Controls → Domain-wide delegation with scope https://www.googleapis.com/auth/gmail.send. We sign a JWT with the SA's private key and Google returns a token that impersonates the user.
• Microsoft 365: the platform's existing Azure app registration gains Mail.Send Application permission on top of the Delegated one used for Pro tier. Your Global Admin clicks "Start admin consent"; Microsoft opens their consent screen; on success Microsoft redirects back to our callback and we mint a client_credentials token for the tenant. That token is what we use on POST /users/{from}/sendMail.

Setup — Google Workspace

1. On Settings → Email → Enterprise mailbox grants click Add Google Workspace domain.
2. Enter your primary Workspace domain (e.g. company.com) and Create. A Setup pending row appears with the exact client ID + scope you need.
3. In a separate tab, sign into admin.google.com as a super-admin.
4. Go to Security → Access and data control → API controls → Manage Domain Wide Delegation and click Add new.
5. Paste the client ID from step 2 into Client ID, and paste the scope URL into OAuth scopes. Save.
6. Back on the settings page, click Verify and enter any mailbox in your Workspace (e.g. you@company.com). We impersonate them, hit gmail.users.getProfile, and flip the row to Active if it works.

Setup — Microsoft 365

1. On Settings → Email → Enterprise mailbox grants click Add Microsoft 365 tenant.
2. Enter your tenant GUID or verified domain (e.g. company.onmicrosoft.com) and Create.
3. Click Start admin consent — we open Microsoft's admin-consent screen in a new tab.
4. Sign in as a Global Administrator and accept. Microsoft redirects back to us; we call client_credentials against your tenant and flip the row to Active if the token comes back.
5. If the row lands on Error, the most common cause is that the tenant's admin-consent policy is disabled for your app. See Microsoft docs for how to enable it.

Send-path precedence

When the send pipeline resolves a sender, the order is:

1. Enterprise grant match — if there's an ACTIVE grant for the org whose tenantOrDomain matches the From-address domain (and the address is on allowedFromAddresses if that list is non-empty), we dispatch via the grant.
2. Pro-tier mailbox — if the sender has an OAuth-connected mailbox, we dispatch via that.
3. Platform SMTP — otherwise the standard SMTP / Resend / SES path.

Every dispatched email carries metadata.resolvedSender.dispatchedVia: 'org_grant' | 'oauth_mailbox' | 'smtp' for auditing.

Filtering the log

The Email logs page (Settings → Email → Logs) has a Dispatch filter with three chips: All / SMTP / OAuth shared inbox. Enterprise-grant sends appear under a fourth badge — "Enterprise grant" — on individual rows.

Removing a grant

Click Remove on the grant row. That deletes our row; you should also revoke on the provider side:

• Google: remove the client ID from Admin console → Domain-wide delegation.
• Microsoft: revoke consent under Azure portal → Enterprise applications → InsightHire → Permissions → Revoke.

Related

• Custom email (SMTP)
• Team sender addresses
• Calendar & meetings — Microsoft 365 and Google OAuth follow the same patterns for calendars.