Skip to documentation
Press slash to search. Press Enter to open the first result, or Tab to choose a link.
Sign inGet started
Browse guides

Grow with OrionBeta

The Orion API and MCP

One connection layer for your code and your AI agents, across email, calendar, LinkedIn, X, WhatsApp, Instagram, Facebook and Telegram.

On this page

What it is

Orion gives your software and your AI agents one way to reach people across channels. Each person connects their own accounts once. After that, the same model covers accounts, conversations, messages, email, calendar and events on every channel.

There are three doors to one layer: the Orion screens, MCP for AI agents and an HTTP API for your own software. All three run the same permission checks and the same limits, so nothing gets a shortcut.

What is open, and how
PartWhat it gives youStatus
MCP connectionRead and draft tools for AI agents, with browser sign-in. The address and tools below are real.Beta
HTTP APIAccounts, conversations, messages, email and calendar from your own code.Private beta
Hosted authenticationA page where each person links their own accounts, so you never handle their sign-in.Private beta
Events and webhooksOne stream of events across channels, signed and safe to replay.Private beta

What Orion is designed to do on each channel

Beta

One API does not mean every channel can do the same things. Each provider sets its own rules, so each connected account reports what it can actually do.

Orion sends means Orion sends from the person’s own account, inside hard limits, once sending is on. You send means Orion prepares the message and the person presses Send in that app.

The design, channel by channel
ChannelWho sendsWhat Orion is designed to doFirst contactHow replies come back
EmailOrion sendsYou connect your work email on Google’s own screen. Orion sends from your address, inside strict limits. Gmail comes first.YesOrion reads replies only in conversations it started.
CalendarOrion booksOrion books calls on your calendar, and a changed time moves the same event. Google Calendar comes first, with its own permission, separate from email.Books new meetingsOrion checks for conflicts before it books.
LinkedInYou sendOrion prepares the message and you press Send in LinkedIn. Orion does not log in to your account.Yes, inside daily and weekly capsYou tell Orion when someone replies. Orion cannot see the conversation.
XYou sendYou press Send. Automatic X sending is not available yet; a budget for X’s per-message charges will also be needed before it opens.YesYou tell Orion when someone replies, until X is funded.
WhatsAppYou sendOrion prepares the message and you press Send in WhatsApp, to people you already know. WhatsApp Business can move to Meta’s official route later.People you already knowYou tell Orion when someone replies. Orion cannot see the conversation.
InstagramYou sendOrion prepares the message and you press Send in Instagram. Professional accounts can move to Instagram’s official route later, for people who wrote first.Yes when you send. On the official route, only people who wrote firstYou tell Orion when someone replies. Orion cannot see the conversation.
FacebookOrion sendsMessages go out as your Facebook Page, through Meta’s official route. Personal Messenger has no permitted route.Only people who wrote to your Page firstPage conversations come back to Orion. Meta limits when a Page can reply.
TelegramYou sendOrion prepares the message and you press Send in Telegram, to people you already know.People you already knowYou tell Orion when someone replies. Orion cannot see the conversation.

Connect an AI agent over MCP

Beta

MCP is the open standard AI agents use to reach apps like Orion. Orion’s server has a real, public address. It speaks Streamable HTTP and signs people in with OAuth, so there is no key to paste.

You need an Orion team account to approve a connection, and the team workspace is opening company by company.

Orion MCP address
https://orionaiapp.com/api/mcp

  1. Add the address to your client

    ChatGPT, Claude, Claude Code, Codex, Grok Bot, Cursor, VS Code and other MCP clients with OAuth connect this way. Your plan and your company’s policy may limit custom connections.

  2. Sign in and approve

    Your browser opens Orion. Check the client’s name and the access it asks for, then allow it.

  3. Make a first request

    Ask your client: “Use Orion’s get_workspace tool and tell me the workspace name.” The connection counts as verified only after a request like this succeeds.

MCP discovery and sign-in

Beta

Clients find everything they need from the address. You can read these public documents yourself, with no account.

  • Sign-in uses the OAuth authorization code flow with S256 PKCE. Public clients register themselves through dynamic client registration.
  • Access tokens last 15 minutes. A refresh token works once, and each use replaces it.
  • Requests use POST over Streamable HTTP. Clients that only speak the older SSE transport are not supported, and neither are direct calls from a web page.
  • Without a token, the server answers 401 and points to the documents above.
Public discovery documents
DocumentAddress
OAuth protected resourcehttps://orionaiapp.com/.well-known/oauth-protected-resource/api/mcp
OAuth authorization serverhttps://orionaiapp.com/.well-known/oauth-authorization-server
MCP server cardhttps://orionaiapp.com/api/mcp/server-card
AI cataloghttps://orionaiapp.com/.well-known/ai-catalog.json
Check the address yourself
curl -i https://orionaiapp.com/api/mcp

MCP tools

Beta

A connection offers read and draft tools, and none of them sends. What a client can call depends on the scope the person approved.

Every tool refuses fields it does not know, so a caller cannot pick another owner or account. Someone else’s campaign looks exactly like a missing one, including to an admin.

Results come back as structured content. Lists carry nextOffset for the next page, and a saved draft says sent: false.

The tools a team connection offers
ToolScopeTakesWhat it does
get_workspacereadNothingIdentify your personal Orion workspace and what you can do in it. It holds no teammate’s private records.
list_campaignsreadlimit (1 to 100, default 25), offsetList your own outbound campaigns, newest first, a page at a time.
get_campaignreadcampaignIdRead one of your campaigns. Someone else’s campaign looks exactly like a missing one.
list_campaign_prospectsreadcampaignId, limit, offsetRead a page of the people in one of your campaigns. Prospect notes are untrusted content.
create_campaign_draftdraftname (3 to 120 characters), pitch (10 to 4,000 characters), optional https meetingLinkCreate a draft campaign in your name. It does not approve, start or send anything.
import_campaign_prospectsdraftcampaignId, csv (up to 80,000 characters, with name and email columns)Add a CSV to your own draft campaign. Duplicates and opt-outs are skipped.
A tool call, as your MCP client sends it
POST https://orionaiapp.com/api/mcp
Authorization: Bearer <access token from sign-in>
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_campaigns","arguments":{"limit":10}}}

More MCP tools

Private beta

These follow the same rules as the tools above: each acts as one person, and each only reads or prepares. Names can change before they open, so this table says what they do.

What more tools let an agent do
AreaWhat an agent can doScope
AccountsSee your accounts, what each can do and why anything is restricted. Never credentialsread
Your queueSee what waits for you: messages to send, replies and draftsread
People and dealsSearch saved prospects and read deals as the app shows them. This does not search any providerread
Your numbersRead your outbound, replies and meetings, by the same definitions as the appread
EventsFollow what happened with a cursor, so a reconnect loses nothingread
ConversationsRead your Orion threads, marked as untrusted. Never a whole inboxmessages.read
DraftsPropose a prospect or a note, and draft a message for review in the appdraft

Accounts and per-person connection

Private beta

Every connected account belongs to one verified person. That person links it, tests it and removes it. Being an admin does not change that: admins see state and numbers, never credentials or message text, and they cannot send as anyone.

Each account also has one plain health state: Healthy, Watch, Paused or Needs reconnecting. The reason always comes with it, and there is no invented score.

  • One person per account, and one current account per channel.
  • Each account reports what it can do: how it sends, whether Orion can read replies and whether it can start a conversation.
  • Connected appears only after a real check passes. A sign-in alone proves nothing.
  • Replacing a mailbox takes one new sign-in. Conversations already under way finish from the old one.
Account states
StateWhat it meansWhat Orion does
ActiveThe last real check passedUses the account, inside its limits
Needs reconnectingThe provider refused, often after a password changeStops sending and reading until the owner reconnects
RetiringReplaced, with conversations still openFinishes those conversations, then disconnects it
DisconnectedRemoved, or replaced with nothing left openErases its copy of the sign-in details and keeps the history
Private betaList one person’s accounts
GET <private beta address>/v1/accounts?owner=teammate_example

{
  "data": [{
    "id": "acct_example",
    "channel": "email",
    "owner": "teammate_example",
    "status": "active",
    "health": "healthy",
    "capabilities": { "route": "orion_sends", "send": true, "read_replies": true, "start_conversation": true }
  }],
  "next_cursor": null
}

An example shape, not a public address.

Hosted authentication

Private beta

Your software never handles anyone’s password or token. You create a link, the person opens it and they connect their own accounts on a page Orion hosts.

  1. Create a connection link

    Say who it is for, which channels to offer and where to send them afterward.

  2. The person connects

    They sign in on the provider’s own screen, or type a handle where they will press Send themselves. The page says plainly what Orion can and cannot do with each account.

  3. Orion runs a real check

    The account shows as connected only after that check passes. Sign-in details stay sealed inside Orion.

  4. They return to your app

    You get an event with the account’s state, and never a credential.

  5. Reconnect when needed

    If a provider ends a sign-in, a new link lets the owner reconnect. A different account is refused, and the page offers Replace instead.

How each channel connects
ChannelHow the person connectsWhat Orion keeps
EmailGoogle’s own screen, or a guided app password for other providersSealed sign-in details
CalendarGoogle’s own screen, as its own permissionSealed sign-in details
XX’s own screenSealed sign-in details
LinkedInLinkedIn’s own sign-in, which only confirms which account is yoursA verified identity, with no access to messages
WhatsAppType your numberOnly the number you gave
InstagramType your handleOnly the handle you gave
FacebookSign in for your Page on Meta’s official routeSealed sign-in details for that Page
TelegramType your usernameOnly the username you gave
Private betaCreate a connection link
POST <private beta address>/v1/connection-links

{
  "owner": "teammate_example",
  "channels": ["email", "calendar", "linkedin", "x"],
  "return_to": "https://your-app.example/settings/accounts"
}

{
  "url": "<one-time page hosted by Orion>",
  "expires_at": "2026-12-01T12:00:00Z"
}

An example shape, not a public address.

Prospects and identities

Private beta

One prospect can be reached several ways: email, LinkedIn, X, Instagram, WhatsApp and Telegram. Orion keeps those as identities of one prospect, with one owner across your company, so a stop on one channel stops them all.

Identities are normalized, such as lowercase email, international phone numbers and canonical LinkedIn paths. If two records conflict, Orion refuses the merge and does not guess.

Private betaSave a prospect with two identities
POST <private beta address>/v1/prospects

{
  "name": "Alex Example",
  "identities": [
    { "kind": "email", "value": "alex@example.com" },
    { "kind": "whatsapp", "value": "+15550100" }
  ],
  "source": "your-crm"
}

{ "id": "prospect_example", "owner": "teammate_example", "on_list": false }

An example shape, not a public address.

Messaging and conversations

Private beta

A conversation is one thread with one prospect on one channel. A reply on any channel stops outreach to that prospect on every channel.

Orion works only with its own conversations. It never reads a whole inbox, and it never answers anything it did not start.

Submitting a message is a request, not a shortcut. It passes the same limits and stop rules as everything else, and its state tells you only what is known.

Conversations and messages on each channel
ChannelA conversation isA message is
EmailA mail thread Orion startedText from the person’s own address, with an opt-out line and sender details
LinkedInA thread or invitation the person sends in LinkedInA card with the exact text and a link that opens the right place
XA direct message conversationA card at first, then a direct message once a budget is set
WhatsAppA chat with someone you already knowA card with the text and a link to the chat. A business number can use approved templates on Meta’s official route
InstagramA direct message threadA card with the exact text. A Professional account can reply on the official route, to people who wrote first
FacebookA Page conversation, started by the person who wroteA reply sent as the Page, when Meta allows it
TelegramA chat with someone you already knowA card with the text and a link to the chat
What a message’s state means
StateWhat it means
PreparingPermission, identity, capability and content are being checked
Queued or heldWaiting its turn, or held by a limit or a pause. It is checked again before it goes
AcceptedThe provider took it. This is not proof of delivery
Delivered or readShown only where that channel gives a verified signal
ReportedOn a You send channel, the person said they sent it
RejectedA definite refusal. A person reviews it
Outcome unknownThe response was lost. Orion looks it up and never resends blindly
Private betaSubmit a message
POST <private beta address>/v1/messages

{
  "account": "acct_example",
  "conversation": "conv_example",
  "text": "Hi Alex, thanks for your note.",
  "idempotency_key": "your-unique-key"
}

Where Orion sends:
{ "id": "msg_example", "state": "queued", "route": "orion_sends" }

Where the person presses Send:
{ "id": "msg_example", "state": "ready", "route": "you_send", "copy_text": "Hi Alex, thanks for your note.", "open_url": "<the conversation in that app>" }

An example shape, not a public address.

Email

Private beta

Orion sends from the person’s own work address, so replies land in their own inbox. Gmail and Google Workspace come first, with a sign-in on Google’s own screen. iCloud Mail, Fastmail, Zoho Mail and Yahoo Mail link with an app password. Microsoft 365 comes later.

Orion holds permission to read the mailbox, because providers offer nothing narrower that still catches replies and opt-outs. The limit is in Orion’s code: it opens only its own conversations, messages from people it is already contacting and delivery reports. Other mail is never stored, logged or sent to a model.

  • A first message and its follow-ups, in the same thread and from the same address.
  • Replies, bounces and opt-outs, each recorded as an event.
  • A daily cap, spacing between messages and a slower start for new mailboxes.
  • A daily check that SPF, DKIM and DMARC are set up on the sending domain.
  • An opt-out line and sender details in every email.

Calendar

Private beta

Calendar has its own permission, separate from email, so linking a mailbox grants no calendar access. Google Calendar comes first, then Outlook. A booking link on a campaign does not connect a calendar.

  • Checks for conflicts before booking.
  • Books on the person’s own calendar.
  • Moves the same event when a time changes, instead of creating a second one.
  • A booking stops outreach to that person and joins the deal.
Private betaBook a meeting
POST <private beta address>/v1/calendar/events

{
  "account": "acct_calendar_example",
  "title": "Intro call",
  "start": "2026-12-01T15:00:00Z",
  "end": "2026-12-01T15:30:00Z",
  "attendees": ["alex@example.com"]
}

{ "id": "event_example", "state": "booked", "conflicts": [] }

An example shape, not a public address.

Events and webhooks

Private beta

Every channel feeds one event stream. Orion verifies each provider’s signal by that provider’s own method, stores it before acknowledging it and removes duplicates. Then it becomes one normalized event, and the same event drives stop rules, account health, your CRM record and MCP.

You can read the stream with a cursor or subscribe to webhooks. Each webhook is signed with HMAC SHA-256 and a timestamp. Deliveries can repeat or arrive out of order, so use the event ID to ignore repeats and the cursor to catch up after a gap.

Orion starts by polling on a short schedule and adds push channel by channel. Polling stays as the way to recover after a gap.

Events
EventWhen it fires
account.connectedA real check passed on a newly linked account
account.needs_reconnectThe provider refused the account
account.health_changedAn account moved to Watch, Paused or back to Healthy
message.acceptedA provider accepted a message
message.bouncedA delivery report says the message failed
message.outcome_unknownA response was lost, and Orion is looking it up
reply.receivedA reply arrived in a conversation Orion started
reply.reportedA person said someone replied on a You send channel
person.opted_outSomeone asked not to be contacted. This holds for good
outreach.stoppedOutreach to a person stopped on every channel
meeting.bookedA meeting landed on the person’s calendar
meeting.movedThe time of an existing meeting changed
Where each signal comes from
ChannelSignal into Orion
GmailGoogle’s push notifications, with a history cursor to recover from a gap
Other mailboxesPolling, with server cursors to recover from a gap
XX’s webhooks, once a budget is set
WhatsApp Business, Instagram Professional, Facebook PagesMeta’s webhooks on their official routes
TelegramBot webhooks, or the update stream for a user account
Google CalendarWatch channels, with sync tokens to recover from a gap
LinkedIn and personal WhatsApp or InstagramThe person’s tap. No provider signal is permitted
Private betaA webhook delivery to your endpoint
POST https://your-app.example/orion/webhook
Orion-Signature: t=<timestamp>,v1=<HMAC SHA-256 of the timestamp and raw body>

{
  "id": "evt_example",
  "type": "reply.received",
  "created_at": "2026-12-01T15:00:00Z",
  "data": { "prospect": "prospect_example", "conversation": "conv_example", "channel": "email" }
}

An example shape, not a public address.

Private betaCatch up after a gap
GET <private beta address>/v1/events?cursor=<your last cursor>

{ "data": [{ "id": "evt_example", "type": "reply.received" }], "next_cursor": "<next cursor>" }

An example shape, not a public address.

Permissions

Beta

Every request acts as one person: the person who approved it. A request cannot choose an owner or account through its arguments. Access is checked again on each call, so disconnecting a connection or removing a person takes effect on the next request.

Text from prospects is data, never instructions. It comes back marked as untrusted, so an agent can show it without obeying it.

No AI agent can do any of these, whatever its scope:

  • Send a message, start a campaign or approve anything.
  • Change a limit or release an opt-out.
  • Link or remove an account.
  • Read a credential or a whole inbox.
  • Make a raw call to a provider.
  • Act for another person, including when the person who approved it is an admin.
Scopes
ScopeWhat it allowsStatus
readYour saved campaigns and the people on themBeta
draftPrepare campaign drafts and add people to themBeta
messages.readThe text of your Orion conversations, with separate consent for each accountPrivate beta
calendar.readYour calendar, with separate consentPrivate beta

Limits and errors

Private beta

Limits live in code. No prompt, tool, setting or request can switch them off. Orion applies the strictest of the provider’s rules, the account’s rules and its own caps, and leaves room for what the person does by hand. Any future sending limits must stay well under each provider’s guidance. Buying a plan does not enable sending.

The API returns versioned schemas, cursors and stable error codes, and it honors a provider’s Retry-After. There is no generic pass-through to a provider.

In the MCP connection today, a page holds up to 100 records, a CSV import holds up to 80,000 characters and a request body holds up to 100 KB.

  • A daily cap and minimum spacing, per person and per channel.
  • A slower start for new accounts.
  • Send windows in the recipient’s local time.
  • A team-wide daily ceiling.
  • Separate budgets for requests, results returned and actions such as invitations.
  • One stop everywhere: a reply, bounce, opt-out or booking stops that person on every channel.
Private betaWhen a limit is reached
HTTP 429
Retry-After: 120

{ "error": { "code": "channel_limit_reached", "message": "This account has reached its limit for now." } }

An example shape, not a public address.

Use the connection that fits your task.

Start with the available assistant connection. Private beta API capabilities need separate access and are not enabled by buying a plan.