Integrations

An integration is a connected provider account scoped to one organization. The provider reference covers the generated runnable-operation catalog; oxygen integrations list --json is the authoritative current connection list, including connection-only providers. Integrations are the credentials that let you call them.

Two auth modes

Some providers support both; the provider reference marks each one managed, byok, or both. Connecting your own key needs a $99 plan or above (billing). CRMs and third-party sequencers are BYOK-only — the data has to live in your account. Professional Network post search, post engagers and company followers run on Managed credits by default and can instead run on your own Up2Data or ScrapeLi key.

Working with integrations

oxygen integrations list --json
oxygen integrations connect <integration-id> --json
oxygen integrations actions <integration-id> --json
oxygen integrations run <integration-id> <action-slug> --input '{...}' --dry-run --json
oxygen integrations disconnect <integration-id> --json

connect returns an OAuth redirect URL for OAuth providers. For API-key providers, run it without credentials first: the preview names every required field, confirms the zero-credit/no-storage posture, states whether a separate approval is required, and returns a web_url. Open that URL to enter a secret manually without putting it in shell history or process arguments. --api-key remains available for controlled noninteractive use.

Hosted sign-in channels: LinkedIn and WhatsApp

LinkedIn and WhatsApp are not OAuth toolkits — they authenticate through a hosted sign-in link. oxygen integrations connect linkedin --country <cc> and oxygen integrations connect whatsapp return a browser URL: sign in for LinkedIn, or scan the QR from WhatsApp → Settings → Linked Devices. The link is shareable, so the account's owner can connect without an Oxygen login, and it expires after 10 minutes. --country (ISO 3166-1 alpha-2, where that account normally signs in) picks the egress proxy and is required for a new LinkedIn account. It must be one of the 56 countries Oxygen has LinkedIn proxies in; any other is refused with the list. oxygen senders proxy-country <id> --country <cc> moves a connected account's proxy to another of them without reconnecting.

Each channel's own command carries the full option set:

oxygen senders connect --country US --json    # LinkedIn
oxygen whatsapp connect --json                # WhatsApp
oxygen senders disconnect <id> --json
oxygen whatsapp disconnect <id> --json

oxygen integrations disconnect linkedin|whatsapp removes the connected Unipile account. When more than one account is connected it returns multiple_connections with the candidate ids — pass --connection-id to pick one.

Read oxygen billing estimate --json before connecting a LinkedIn account or WhatsApp number. Either needs a paid plan: on Free the connect returns upgrade_required with the plan page. When sender_billing is credit_reservations, the connection reserves monthly credits, and the billing owner's credits must cover the first month. With the legacy sending_seats model, it occupies a dollar sending seat. oxygen billing seats --json reports the current connection eligibility or status: seats_retired. Sending a message has no separate per-message credit charge.

Native provider actions

integrations actions serves two action sources. Composio toolkits return app actions (composio.<toolkit>.<action>). Native BYOK providers — the sequencers and mailbox-infrastructure vendors marked byok in the provider reference — are not Composio toolkits: their actions are the provider's own operations, run with your connected BYOK key. The actions response marks these integrations with source: "native_provider".

The same operations are runnable as integration actions or directly as tools:

oxygen integrations actions salesforge --json
oxygen integrations run salesforge <action-slug> --input '{...}' --live --approved --max-credits <n> --json
oxygen tools run salesforge.<action-slug> --input-json '{...}' --mode live --approved --max-credits <n> --json

Dry-run is the default. Inspect its quote before a live call. A native BYOK call that pays OXYGEN's 0.05-credit platform fee requires --live --approved --max-credits <n>, including read actions (side-effect class none); a ceiling below the quoted fee is refused before the provider call. A zero-fee read may run without approval. The provider bills any provider usage to your connected account separately. oxygen tools run and live Composio toolkit actions likewise require approval and a positive credit ceiling when they can charge credits.

Example: drive Salesforge sequences

# Discover actions, the workspace, and its mailboxes (reads)
oxygen integrations actions salesforge --json
oxygen integrations run salesforge get_workspaces --live --json
oxygen integrations run salesforge get_workspaces_by_workspace_id_mailboxes --input '{"workspaceID":"ws_123"}' --live --json

# Create a sequence (write: dry-run, inspect, then approve)
oxygen integrations run salesforge post_multichannel_workspaces_by_workspace_id_sequences --input '{"workspaceID":"ws_123","name":"Q3 launch outreach"}' --dry-run --json
oxygen integrations run salesforge post_multichannel_workspaces_by_workspace_id_sequences --input '{"workspaceID":"ws_123","name":"Q3 launch outreach"}' --live --approved --max-credits 20 --json

# Enroll contacts, then launch (same gate)
oxygen integrations run salesforge post_multichannel_workspaces_by_workspace_id_sequences_by_sequence_id_enrollments --input '{"workspaceID":"ws_123","sequenceID":42,"filters":{...}}' --live --approved --max-credits 20 --json
oxygen integrations run salesforge patch_multichannel_workspaces_by_workspace_id_sequences_by_sequence_id_launch --input '{"workspaceID":"ws_123","sequenceID":42}' --live --approved --max-credits 20 --json

..._enrollments_remove removes enrollments with the same filter shape. Sequence steps, schedules, and settings patch the same way — integrations actions lists every operation with its input schema.

Sending-pool boundary

Connecting Salesforge or Mailforge does not add their mailboxes to Oxygen's native sending pool. The native sequencer sends only through Google and Microsoft OAuth mailboxes — imported inline or pulled from a connected Zapmail workspace — over the Gmail API and Microsoft Graph; there is no SMTP transport, so mailboxes hosted on Salesforge/Mailforge infrastructure cannot join it. "Sending through Salesforge" means driving Salesforge's own sequences with the actions above: the sends execute on Salesforge's side. Its campaign metrics stay readable as raw provider operations (get_workspaces_by_workspace_id_sequence_metrics, get_workspaces_by_workspace_id_sending_data), but Salesforge exposes no attributed reply/bounce rollup by mailbox, and those campaigns do not appear in Oxygen's mailbox/domain analytics.

Connection shape

Provider events

Many integrations emit events when something happens on the provider side (HubSpot contact created, Instantly reply, Attio record updated). Events can fire workflow triggers.

oxygen integrations events list --json
oxygen integrations events enable --source instantly --event email.reply_received --json
oxygen integrations events disable --source instantly --event email.reply_received --json
oxygen integrations events deliveries --json

deliveries lists recent webhook deliveries and the workflow runs they started — check it before debugging why a workflow did or did not fire.

Mirroring external state

An external write — CRM contact create, outbound enrollment, a LinkedIn action — should mirror its result back into the originating table through the tool/action column that made it:

Provider-specific docs

Per-provider quirks, rate limits, and mapping examples live in the Oxygen agent skills. install defaults to every skill for Codex, Claude Code, and Cursor:

oxygen skills install --json

Supabase

Supabase is a connection-only database source for Tables, not a generic provider-action toolkit. Oxygen accepts only managed Supabase PostgreSQL or pooler hosts, requires TLS, resolves the host again in the worker, and encrypts the connection string. Use a dedicated read-only database role: connection validation refuses superuser, role/database creation, replication, schema creation, or table write privileges anywhere outside PostgreSQL system schemas.

MCP never accepts the credential. oxygen_supabase_connection_open returns the secure Connections page for the user to paste it into. In a terminal, oxygen supabase connect --database-url-stdin is the only supported credential input so the URL does not appear in process arguments. Connection validation, catalog inspection, plans, imports, and refreshes cost 0 Oxygen credits; Oxygen reads the selected source schemas and never writes to Supabase. A destination Table that already carries a standing auto-run subscribed to imports is the one thing an import can make spend — the plan discloses it per table before you start. One import carries at most 50 source tables.

Breakcold

Breakcold is BYOK with a bc_live_ key. Run connect without a credential first — nothing is submitted or stored, and the response names the expected format and setup location:

oxygen integrations connect breakcold --json
oxygen integrations connect breakcold --api-key '<bc_live_...>' --json

Create the key in Breakcold Settings → API keys, limit its workspace access, and grant only the scopes the operations you plan to call need — never a write or send scope for a read-only workspace. Oxygen validates the submitted key with GET /workspaces, which Breakcold prices at zero tokens and Oxygen charges 0 credits for, before storing it.

Each operation's exact scope, token cost, and side-effect class is on its descriptor — read it with oxygen tools get breakcold.<operation> --json. Most successful Breakcold reads cost 0.2 and writes 0.4 Breakcold tokens; a call on your connected key also pays OXYGEN's 0.05-credit platform fee.

• Legacy breakcold-usr… credential — those keys do not authenticate against Breakcold API v1. Create a new bc_live_… personal key in Settings → API keys and reconnect.
• HTTP 412 from /rest/me — that is Breakcold's deprecated API surface. Oxygen uses https://rest.breakcold.com/api/v1 with Bearer authentication.
• oxygen integrations test breakcold is unsupported — Breakcold has no stored-key validator, so test returns the free connect ... --json preview command. A stored Breakcold key cannot be re-checked in place; reconnect with a fresh credential instead.
• No authorized workspace — the key is valid but its workspace limit excludes everything. Fix it in Breakcold Settings → API keys, then reconnect.

Breakcold's own API overview and authentication docs.

Related

• Provider reference — generated runnable-operation catalog and auth modes.
• Provider catalog — how tools are grouped and priced.
• Connect and warm up existing mailboxes — the general Google, Microsoft individual, and Entra tenant onboarding workflow into OXYGEN Warm-up.
• Mailbox warmup and monitoring compatibility — the closed origin/platform/auth matrix for OXYGEN Warm-up and EmailGuard monitoring.
• Waterfalls — combining multiple integrations for fallback.
• Columns — wiring row work to provider actions.