Connect and warm up existing mailboxes

Use this guide when the mailboxes already exist outside OXYGEN. They may be pasted directly or imported from any authorized CSV, JSON, JSONL, or XLSX export. The source vendor is provenance only; it does not change the Google or Microsoft authorization model.

Connection prices of 100 credits below apply to ordinary Google and Microsoft mailboxes. Entra uses 25 credits ($0.25) per inbox-month for Sequencer and included warm-up; see Entra pricing and limits.

One OXYGEN journey, two independent authorizations. First authorize the exact mailbox for OXYGEN Sequences. Then satisfy the separate OXYGEN Warm-up connection. Importing an address alone does neither, and warm-up never starts recurring billing without an approved quote.

End-to-end workflow

1. Open Accounts → Email → Add inboxes.
2. Choose Connect existing to paste exact addresses, or Import a file for an authorized provider export.
3. Review the provider, tenant, and mailbox counts before registration.
4. Authorize native OXYGEN sending using the Google or Microsoft method below.
5. Complete the separate OXYGEN Warm-up prerequisite for every selected mailbox.
6. Review the exact mailbox scope, ramp, recurring price, and current-cycle credit ceiling.
7. Approve that plan or continue without warm-up.
8. Confirm sending authorization and warm-up status in OXYGEN.

OXYGEN never scans a domain or imports a Google Workspace or Entra directory. Only explicitly submitted addresses can enter the sending pool.

Keep replacement inboxes warm

In Accounts → Email, open an inbox's Settings and choose Keep on standby, or select several inboxes and use the bulk action. Review the affected campaigns before confirming: pending outreach from these inboxes will be held. Existing warm-up keeps running. This action starts no warm-up subscription or purchase; connection and warm-up charges continue under their existing subscriptions.

The Standby reserve shows ready inboxes, confirmed warm-up sending days and blockers. Readiness is assessed after you keep an inbox on standby. Until the first check, it shows Readiness pending rather than a zero-day count. Existing confirmed warm-up days carry over; standby does not restart the count. Readiness requires 14 confirmed sending days by default, running warm-up, current authorization and passing DNS readiness. Missing or stale evidence blocks promotion. You can change the required days in this reserve. Choose Use for outreach to return an inbox to normal campaign use.

Each campaign can enable Automatically replace paused mailboxes in its sending settings. Review the shared reserve before enabling it: a replacement uses its own sender name and signature and may belong to another person. When mailbox bounce protection pauses an outreach inbox, a ready reserve can take its uncontacted leads. Already contacted leads keep their original inbox; follow-ups wait while it is paused, and incoming replies remain collected. Exact-inbox steps hold for review.

A shortage waits for a ready reserve. Replacement keeps daily limits, ramps, schedules, suppression and campaign-wide safety pauses, and the original inbox stays paused until repaired. Replacement history appears beside these controls. Turning automatic replacement off also stops existing replacements from serving that campaign until it is enabled again.

Choose the authorization path

The important Microsoft distinction is that tenant authorization can replace individual mailbox sign-ins for native OXYGEN sending, but it does not replace per-mailbox OXYGEN Warm-up consent for imported, manual, or other mailboxes outside an approved OXYGEN managed-mailbox order.

Add the exact mailbox identities

Adding a mailbox needs a paid plan. On Free, importing or authorizing an address the workspace does not hold yet returns upgrade_required with the plan page; previews, and re-authorizing mailboxes you already hold, stay open.

Connect existing

Paste up to 500 exact Google or Microsoft addresses into Connect existing. Choose the actual hosting provider; Microsoft Azure/Entra mailboxes still use Microsoft transport. OXYGEN registers only those addresses and shows the provider-specific authorization review.

Import a file from any source

The browser and CLI accept CSV, JSON, JSONL, and XLSX files up to 500 rows and 5 MB. The source label is optional provenance, not a connection mode.

Useful fields are:

Microsoft passwords, OAuth tokens, authorization codes, MFA/TOTP seeds, client secrets, service-account keys, and delegation keys are rejected. Never paste a mailbox credential into chat or pass it through MCP. A Google app password may enter only through the signed-in browser import or local CLI credential-file path, where it is encrypted immediately and never returned.

Every inbox belongs to a sender

An inbox is always somebody's: OXYGEN attaches every imported inbox to a sender profile — the person it sends as, shared with that person's LinkedIn and WhatsApp senders — so a campaign can send every channel from one identity and an inbox never sits in an anonymous pool.

You decide who that is, in this order:

• oxygen mailboxes import --sender <profile-id> (or sender_profile_id in the request body) puts the whole import under one person. List ids with oxygen senders profiles list, or create a person with oxygen senders profiles create.
• A row's own sender_profile_id overrides that for one inbox.
• Otherwise OXYGEN derives the person from the row: first_name + last_name first, then display_name. A profile of that name already in the workspace is joined rather than duplicated, so a second inbox for Talia lands on Talia.
• With none of those, OXYGEN creates a profile named from the address local part (alex.rivera@… → "Alex Rivera"), marks it auto-created, and the import receipt counts it under sender_profiles.created — rename it with oxygen senders profiles update <id> --name "...".

An inbox with no From display name of its own takes the sender's name, so the person's name reaches the header the moment they are attached.

Moving an inbox means attaching it to the other sender, not detaching it: oxygen senders profiles attach <other-profile-id> --mailboxes <mailbox-id> reassigns it. Detaching an inbox is refused (there is no unassigned pool for one to return to), and deleting a profile that still owns inboxes is refused until they are moved — its LinkedIn and WhatsApp accounts detach normally.

Authorize native OXYGEN sending

Native authorization lets OXYGEN Sequences send and read replies. It does not start warm-up and cannot be inherited from the mailbox's source application. In the app, the sign-in also brings the mailbox's mail history into Unibox and its business activity into CRM. That connection is listed at 100 credits per mailbox-month; check oxygen billing commitments --view connection-prices --json before you approve.

Google Workspace

Each Google mailbox completes its own Google OAuth sign-in. The returned grant is bound to that exact Google account and OXYGEN workspace.

Microsoft 365

In the app, each Microsoft mailbox signs in once, the same way as a Google mailbox. There is no connection method to choose. Only if the app says the managed Microsoft connection isn't available yet does it offer Use OXYGEN's Microsoft sign-in instead, which connects the mailbox for sending only, without mail history or CRM. If Microsoft asks for admin approval, a Microsoft 365 administrator approves access first, and the mailbox owner signs in again. An individual run is capped at 10 links so its consent and retry scope stays reviewable; this is a batch limit, not a workspace limit.

Microsoft: dedicated sending tenant (agents)

An agent can connect mailboxes that belong to a dedicated Microsoft sending tenant with one administrator approval instead, through oxygen mailboxes connect-oauth --vendor oxygen --provider microsoft --authorization-mode tenant (MCP: oxygen_mailboxes_connect_oauth). This authorizes sending only and is not offered in the app.

For Microsoft's built-in roles, the person opening the link must be a Global Administrator or Privileged Role Administrator. Tenant mode asks for the Microsoft Graph application permissions Mail.Send and Mail.Read; Microsoft does not allow the standard Application Administrator or Cloud Application Administrator roles to consent to Microsoft Graph application roles. If the tenant uses a custom consent role, its Entra team must confirm that the role's policy explicitly covers those Graph app roles. See Microsoft's tenant-wide admin-consent role matrix.

• OXYGEN groups the exact submitted addresses by resolved Entra tenant.
• One administrator opens one authorization link for each resolved tenant.
• Microsoft grants application access at tenant level.
• OXYGEN then performs read-only Graph probes for only the submitted addresses and enables only those that pass.
• No directory is listed, discovered, or imported.
• A missing, inaccessible, or wrong-tenant address remains Needs connection.

The provider grant is tenant-wide. OXYGEN enforces the selected-address boundary at verification and every send. A customer that also wants Microsoft itself to enforce a narrower boundary can configure Exchange Application RBAC separately. This is a customer-owned Microsoft configuration: OXYGEN does not create, inspect, or verify the tenant's Exchange Application RBAC scope.

One Entra tenant authorization never covers a different Entra tenant. A mixed selection produces one administrator step per resolved tenant.

Mailboxes purchased through OXYGEN

OXYGEN normally authorizes the native sending connection unattended after the sending domain's approval lands. Use the status and remedy shown in Accounts:

• Waiting on approval needs no mailbox-owner action; OXYGEN keeps checking.
• Authorize now lets a workspace administrator retry the unattended path.
• Connect or Not sending means automatic authorization cannot finish; each affected mailbox owner completes the OXYGEN browser authorization shown.

Do not obtain or paste a managed mailbox password. This native-send status does not change the managed OXYGEN Warm-up path below.

Set up OXYGEN Warm-up

Warm-up is a separate destination connection because a native Google or Microsoft sending grant cannot be transferred to the managed warm-up service; the one exception is Gmail connected with the app's Google sign-in, below. The customer stays inside the OXYGEN journey and does not need to create or manage a separate warm-up-provider account.

Google Workspace

• Gmail connected with the app's Google sign-in warms up over that connection: approving the oxygen mailboxes warmup enable preview grants standard mailbox access (send, read and organize) with no second Google sign-in, and disabling warm-up revokes it. If this is not available for an inbox yet, oxygen mailboxes compatibility says so and points you to OXYGEN support.
• A compatible imported Google app password can normally continue into warm-up without a second Google browser login.
• Any other Google inbox without an app password needs a separate Google warm-up authorization from someone who controls that exact mailbox (oxygen mailboxes warmup google, below); until then warm-up reads consent_required.
• OXYGEN never converts its Google OAuth refresh token into a warm-up password.

Microsoft 365 and Entra

Every eligible Microsoft mailbox outside an approved OXYGEN managed-mailbox order completes one OXYGEN Warm-up Outlook authorization. This remains true even when one Entra administrator authorized the whole selected set for native OXYGEN sending.

There is currently no tenant-wide shortcut for this warm-up step. One mailbox's Outlook consent cannot authorize another mailbox. Microsoft passwords and app passwords are never accepted as a fallback.

Managed mailboxes

An OXYGEN managed-mailbox order can activate warm-up automatically after provisioning only when the approved quote explicitly contains the exact future addresses, warm-up ramp, recurring price, credit ceiling, and automatic_after_provisioning=true. That order approval is authority for its own scope only. Otherwise the mailbox uses the standalone warm-up preview.

Review price before activation

For existing or imported mailboxes, the first Enable OXYGEN Warm-up action is a zero-credit, no-provider-write preview. It returns:

• eligible and blocked addresses;
• the proposed ramp, normally four weeks;
• the live recurring price: 100 credits per warming mailbox-month, or 0 when warm-up is included in the mailbox's 100-credit monthly connection (included_in_connection says which);
• the maximum current-cycle credit charge; and
• a plan hash bound to the exact scope, credential revision, ramp, and price.

Only a matching approved action may create the warm-up connection, reserve or capture credits, and start the ramp. If any bound input changes, OXYGEN returns plan_stale and requires a fresh review. The operator may explicitly continue without warm-up.

CLI equivalent

Use the web journey for ordinary onboarding. Operators can inspect the same contract through the CLI.

Validate a provider-neutral identity export locally:

oxygen mailboxes import --file ./mailboxes.csv \
  --vendor provider-export --validate-only --json

Inspect the registered mailboxes:

oxygen mailboxes compatibility --json
oxygen mailboxes oauth-health --json

Preview the connection the app makes for a Google or Microsoft mailbox — sending plus mail history in Unibox and business activity in CRM, up to 10 exact addresses per run, listed at 100 credits per mailbox-month:

oxygen mailboxes connect-oauth --vendor composio --provider google \
  --mailboxes [email protected] --json

--vendor oxygen connects a mailbox for sending only, without history or CRM. Preview its native authorization for a dedicated Microsoft sending tenant:

oxygen mailboxes connect-oauth --vendor oxygen --provider microsoft \
  --authorization-mode tenant \
  --mailboxes [email protected],[email protected] --json

Use --authorization-mode individual for a sending-only sign-in on an ordinary company or personal Microsoft mailbox:

oxygen mailboxes connect-oauth --vendor oxygen --provider microsoft \
  --authorization-mode individual \
  --mailboxes [email protected] --json

Google always uses individual OAuth.

Gmail connected with the app's Google sign-in needs no separate warm-up authorization: preview oxygen mailboxes warmup enable directly. For any other Google inbox without a managed or imported app password, preview its separate warm-up authorization:

oxygen mailboxes warmup google --mailboxes [email protected] --json

Approve the fresh setup plan with --approved --plan <plan_hash> --max-credits 0, open its returned link as that exact Google inbox, then poll with --status. Google shows the warmup provider's application. This setup transfers no native grant or password, starts no warm-up and charges no credits. After authorization, preview and approve warm-up enrollment separately. In the app, Enable Warmup asks for this Google sign-in only when the inbox needs it, then returns to the enrollment confirmation.

For a Microsoft mailbox outside an approved OXYGEN managed-mailbox order, preview the separate warm-up consent:

oxygen mailboxes warmup microsoft \
  --mailboxes [email protected],[email protected] --json

Then preview the priced warm-up plan. A paid enrollment ramps until 28 days with a provider-confirmed warm-up send (stalled days extend the ramp), then keeps warming at 10 emails a day, billed monthly, until you disable it; --ramp-weeks only spreads the volume climb:

oxygen mailboxes warmup enable \
  --mailboxes [email protected],[email protected] \
  --ramp-weeks 4 --json

Do not approve by copying placeholders from documentation. Review the current response, then echo its fresh plan hash and exact credit ceiling into the approved command.

Without --mailboxes the plan covers the whole pool. One preview and approval holds at most 220 mailboxes; a larger scope is refused with warmup_scope_too_large, so split the pool into --mailboxes batches and preview each one.

Verify and recover

Never warm the same mailbox on two networks. Cancel any existing source-provider warm-up before approving OXYGEN Warm-up.

Read mailbox health freshness

oxygen mailboxes health --json returns stored health evidence. Read healthFreshness independently of the score and healthSyncStatus:

healthEvidenceAt dates the measurement; healthPolledAt dates a successful provider read. An empty successful read advances the poll time without refreshing the measurement. Older checked-at timestamps alone do not establish measured evidence. Mailbox get/list expose these fields under deliverability using health_freshness, health_evidence_at and health_polled_at.

The last recorded sync status is ok after a successful read, including an empty result; blocked after a plan refusal; or failed after a failed read. unknown means no recognized refresh outcome is recorded, which can apply to older readings. It does not establish success or the absence of a blocker. Read healthSyncReason (or deliverability.health_sync_reason) alongside it.

blocked with byok_requires_paid_plan means the workspace plan prevents the read. Reconnecting the provider does not resolve this subscription restriction. Eligibility is rechecked automatically. Background health sync checks due inboxes every three minutes in bounded batches, normally after 24 hours since their last successful poll. Queued work, provider backoff and missing connections can delay checks; the schedule does not guarantee a new measurement.

Missing warm-up history or enabled without sends

An enabled warm-up or an advancing ramp day does not prove that mail was sent. Start with a read-only snapshot of the exact mailbox:

oxygen mailboxes get [email protected] --json

Inspect warmupMetrics.sent (successful sends), attempted, and daily.

The pause codes runaway_dispatch and send_failure_rate mean OXYGEN's safety checks found excessive dispatch or too few successful sends. Use the reported pause reason and dated daily evidence to investigate. Lifetime attempt totals may span previous ramps and cannot be compared directly with a per-day cap. An active provider status or healthy DNS does not prove that its credential can send; compare exact successful-send timestamps and counters with a dated baseline before claiming recovery. Pauses stay paused until reviewed and explicitly resumed.

The fleet health warmup.byCause counts currently paused or errored inboxes. Old failure evidence retained on a recovered, warming inbox is not a current stop and is excluded from that count. Mailbox health and OAuth health exclude deleted inboxes; retained disabled inboxes remain visible so their status and authorization needs can be inspected.

A paused seat with warmupTruth.billing.status: pending needs enrollment-hold recovery, not an assumption that its subscription is already confirmed. Its compatibility and warm-up truth fields both point to the enrollment preview.

Daily sent buckets count attempts, not necessarily successful sends. Today's bucket is a partial day at the capture time. Native campaign usage such as lastUsedAt is separate from warm-up activity.

mailboxes warmup status is not a read-only inspection: it persists refreshed state and may automatically pause a runaway mailbox. Use it only when that protective action is in scope. A refresh does not authorize campaign sends. Do not disable/re-enable warm-up to repair a missing graph: disabling cancels the seat, and re-enrollment requires a new quote and approval. Follow an evidenced connection or configuration remedy without resetting a healthy ramp.

mailboxes warmup reconnect also changes the provider connection and can restart its history. It is for an evidenced connection fault, not a stale-chart repair.

daily_captured_at records the last successful daily-history read. daily_history_attempted_at also advances on a failed read, allowing other inboxes their turn. Each sync reads daily detail for at most 25 inboxes, ordered by the oldest attempt. Worker scheduling, pool size and provider errors affect freshness; there is no guaranteed next-capture timestamp.

For OXYGEN Warm-up, normalized inbox_rate and deliverability_rate both reflect the provider statistics response's inbox rate; health_score is its health score. The raw vendor_warmup_metrics snapshot is a separate provider response and may disagree. OXYGEN does not define the provider's scoring formula or silently reconcile these snapshots. None of these scores is an independent placement test.

Common questions

Does every mailbox connect twice?

There are two authorization contracts, but one guided OXYGEN journey. Google uses native OAuth; warm-up then runs over the app's Google connection, a source app-password handoff, or a separate Google owner consent. Microsoft ordinary accounts use two browser authorizations per mailbox. Through an agent, a dedicated Entra sending tenant can reduce the native stage to one administrator grant per tenant, while non-managed warm-up still needs one consent per mailbox. Mailboxes purchased through OXYGEN can use managed authorization and warm-up handoffs covered by their approved order; follow the exact Accounts status instead of assuming that a second browser step is required.

Can OXYGEN reuse an OAuth grant from the source vendor?

No. OAuth grants are bound to the application, account, tenant, scopes, and audience that obtained them.

Does tenant mode connect the whole Entra directory?

No. Microsoft grants the application tenant-level access, but OXYGEN registers, probes, and enables only the exact submitted addresses. It never lists or imports other directory users.

Does import automatically start warm-up or billing?

No. Import registers mailbox identities. Existing/imported mailbox warm-up starts only after its prerequisites and exact priced plan are approved. The separate managed-order exception applies only when that order's approved quote explicitly grants automatic activation for its exact addresses.

Who sends outbound campaigns?

OXYGEN Sequences. Warm-up authorization does not create a campaign or grant campaign-dispatch authority.

Which inbound mail does AI reply classification read?

Each classified conversation uses credits, so every mailbox has a classification scope. Replies only classifies Sequence threads and threads you wrote in; newsletters, notifications and other mail stay in Unibox unclassified, at no cost. All mail classifies every inbound conversation. A Google mailbox you added yourself starts on Replies only. Every other mailbox starts on All mail: OXYGEN reads only a Microsoft 365 mailbox's Inbox, and a reply to a campaign sent from another platform has no outbound message in OXYGEN to match.

Change it in the mailbox's Settings, with oxygen mailboxes update <mailbox> --classify replies (or all), or with classification_scope on oxygen_mailboxes_update. mailboxes get shows the current scope. A change applies to new mail; oxygen inbox rescan previews and then re-classifies earlier mail. An inbox connected for full-mail sync includes its analysis in the monthly connection, so the setting does not apply to it.

Related

• Mailbox compatibility reference — the complete origin, hosting, and downstream-authentication matrix.
• Approvals — exact scope, previews, and approval tokens.
• Billing and credits — recurring services and credit ceilings.
• Sequences — sender readiness, enrollment, and dispatch.

Entra pricing and limits

Entra Sequencer and warm-up cost 25 credits ($0.25 face value) per inbox/month. Managed hosting remains a separate 4,000 credits ($40) per tenant/month for up to 100 inboxes: 100 inboxes total 6,500 credits ($65) before optional placement or domain charges. Imported Entra accounts pay the connection fee without OXYGEN hosting.

Entra campaign sending is limited to 2 per inbox/day across Sequences, including when the campaign ramp is off. Warm-up is separate: the dedicated tenant limit continues through maintenance (2 per inbox/day at 100 inboxes). Account settings, mailboxes get, and limits show expose the limits in force.