Integrations
Connected provider accounts. The auth state behind every tool call.
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
| Mode | Who pays | Setup |
|---|---|---|
managed | Pay Oxygen credits per call; Oxygen holds the provider key | None |
byok | Pay the provider directly; you connect your own account | OAuth or API key per provider |
Some providers support both; the provider reference marks each one managed, byok, or both. CRMs and third-party sequencers are BYOK-only — the data has to live in your account.
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> --jsonconnect 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.
Unipile-backed channels: LinkedIn and WhatsApp
LinkedIn and WhatsApp are not Composio toolkits — they authenticate through Unipile hosted auth. 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.
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> --jsonoxygen 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.
Connecting a LinkedIn account or a WhatsApp number costs nothing today, and messages sent from them cost no credits. A per-account monthly seat price exists in code behind a flag that is off — see Built, not currently charged.
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> --jsonDry-run is the default. On this native BYOK path, read actions (side-effect class none) run live without approval, and every write requires a dry run first, then --live --approved. Pass --max-credits too — it is accepted and forwarded, though the native branch does not enforce a ceiling, because a BYOK run bills 0 Oxygen credits and the provider bills your connected account directly. The two neighbouring paths do enforce it: oxygen tools run refuses any live operation not classed none/no_bill without both --approved and a positive --max-credits, and every live Composio toolkit action needs the same pair even when it only reads.
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
| Field | Notes |
|---|---|
provider | Provider name |
auth_mode | managed or byok |
status | connected, disconnected, expired, error |
account_label | Provider-side identifier (workspace name, email) |
scopes | Granted OAuth scopes, if applicable |
connected_at, last_verified_at | Timestamps |
last_error | If status is error |
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 --jsondeliveries 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:
| Cell field | Holds |
|---|---|
value | Provider record ID (e.g. hubspot_contact_id) |
provenance.outputs.sync_status | queued, synced, failed |
provenance.outputs.last_synced_at | Timestamp |
error | Provider error text on failure |
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 --jsonBreakcold
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_...>' --jsonCreate 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.
| Work you want to do | Breakcold scopes |
|---|---|
| Inspect or change CRM objects and fields | crm:metadata:read, crm:metadata:write |
| Inspect or change inbox views | inbox:views:read, inbox:views:write |
| Read or write CRM records and custom activities | records:read, records:write |
| Read or write tasks | tasks:read, tasks:write |
| Read or write notes | notes:read, notes:write |
| Read conversations or send messages | inbox:read, inbox:send |
| Read meetings and transcripts | meetings:read |
| Manage integration hooks | webhooks:write |
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; Oxygen charges no credits for these BYOK calls.
- Legacy
breakcold-usr…credential — those keys do not authenticate against Breakcold API v1. Create a newbc_live_…personal key in Settings → API keys and reconnect. - HTTP 412 from
/rest/me— that is Breakcold's deprecated API surface. Oxygen useshttps://rest.breakcold.com/api/v1with Bearer authentication. oxygen integrations test breakcoldis unsupported — Breakcold has no stored-key validator, sotestreturns the freeconnect ... --jsonpreview 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.