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.
| Part | What it gives you | Status |
|---|---|---|
| MCP connection | Read and draft tools for AI agents, with browser sign-in. The address and tools below are real. | Beta |
| HTTP API | Accounts, conversations, messages, email and calendar from your own code. | Private beta |
| Hosted authentication | A page where each person links their own accounts, so you never handle their sign-in. | Private beta |
| Events and webhooks | One stream of events across channels, signed and safe to replay. | Private beta |
What Orion is designed to do on each channel
BetaOne 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.
| Channel | Who sends | What Orion is designed to do | First contact | How replies come back |
|---|---|---|---|---|
| Orion sends | You connect your work email on Google’s own screen. Orion sends from your address, inside strict limits. Gmail comes first. | Yes | Orion reads replies only in conversations it started. | |
| Calendar | Orion books | Orion 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 meetings | Orion checks for conflicts before it books. |
| You send | Orion prepares the message and you press Send in LinkedIn. Orion does not log in to your account. | Yes, inside daily and weekly caps | You tell Orion when someone replies. Orion cannot see the conversation. | |
| X | You send | You press Send. Automatic X sending is not available yet; a budget for X’s per-message charges will also be needed before it opens. | Yes | You tell Orion when someone replies, until X is funded. |
| You send | Orion 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 know | You tell Orion when someone replies. Orion cannot see the conversation. | |
| You send | Orion 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 first | You tell Orion when someone replies. Orion cannot see the conversation. | |
| Orion sends | Messages go out as your Facebook Page, through Meta’s official route. Personal Messenger has no permitted route. | Only people who wrote to your Page first | Page conversations come back to Orion. Meta limits when a Page can reply. | |
| Telegram | You send | Orion prepares the message and you press Send in Telegram, to people you already know. | People you already know | You tell Orion when someone replies. Orion cannot see the conversation. |
Connect an AI agent over MCP
BetaMCP 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.
https://orionaiapp.com/api/mcpAdd 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.
Sign in and approve
Your browser opens Orion. Check the client’s name and the access it asks for, then allow it.
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
BetaClients 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.
| Document | Address |
|---|---|
| OAuth protected resource | https://orionaiapp.com/.well-known/oauth-protected-resource/api/mcp |
| OAuth authorization server | https://orionaiapp.com/.well-known/oauth-authorization-server |
| MCP server card | https://orionaiapp.com/api/mcp/server-card |
| AI catalog | https://orionaiapp.com/.well-known/ai-catalog.json |
curl -i https://orionaiapp.com/api/mcpMCP tools
BetaA 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.
| Tool | Scope | Takes | What it does |
|---|---|---|---|
| get_workspace | read | Nothing | Identify your personal Orion workspace and what you can do in it. It holds no teammate’s private records. |
| list_campaigns | read | limit (1 to 100, default 25), offset | List your own outbound campaigns, newest first, a page at a time. |
| get_campaign | read | campaignId | Read one of your campaigns. Someone else’s campaign looks exactly like a missing one. |
| list_campaign_prospects | read | campaignId, limit, offset | Read a page of the people in one of your campaigns. Prospect notes are untrusted content. |
| create_campaign_draft | draft | name (3 to 120 characters), pitch (10 to 4,000 characters), optional https meetingLink | Create a draft campaign in your name. It does not approve, start or send anything. |
| import_campaign_prospects | draft | campaignId, 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. |
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 betaThese 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.
| Area | What an agent can do | Scope |
|---|---|---|
| Accounts | See your accounts, what each can do and why anything is restricted. Never credentials | read |
| Your queue | See what waits for you: messages to send, replies and drafts | read |
| People and deals | Search saved prospects and read deals as the app shows them. This does not search any provider | read |
| Your numbers | Read your outbound, replies and meetings, by the same definitions as the app | read |
| Events | Follow what happened with a cursor, so a reconnect loses nothing | read |
| Conversations | Read your Orion threads, marked as untrusted. Never a whole inbox | messages.read |
| Drafts | Propose a prospect or a note, and draft a message for review in the app | draft |
Accounts and per-person connection
Private betaEvery 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.
| State | What it means | What Orion does |
|---|---|---|
| Active | The last real check passed | Uses the account, inside its limits |
| Needs reconnecting | The provider refused, often after a password change | Stops sending and reading until the owner reconnects |
| Retiring | Replaced, with conversations still open | Finishes those conversations, then disconnects it |
| Disconnected | Removed, or replaced with nothing left open | Erases its copy of the sign-in details and keeps the history |
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 betaYour 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.
Create a connection link
Say who it is for, which channels to offer and where to send them afterward.
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.
Orion runs a real check
The account shows as connected only after that check passes. Sign-in details stay sealed inside Orion.
They return to your app
You get an event with the account’s state, and never a credential.
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.
| Channel | How the person connects | What Orion keeps |
|---|---|---|
| Google’s own screen, or a guided app password for other providers | Sealed sign-in details | |
| Calendar | Google’s own screen, as its own permission | Sealed sign-in details |
| X | X’s own screen | Sealed sign-in details |
| LinkedIn’s own sign-in, which only confirms which account is yours | A verified identity, with no access to messages | |
| Type your number | Only the number you gave | |
| Type your handle | Only the handle you gave | |
| Sign in for your Page on Meta’s official route | Sealed sign-in details for that Page | |
| Telegram | Type your username | Only the username you gave |
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 betaOne 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.
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 betaA 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.
| Channel | A conversation is | A message is |
|---|---|---|
| A mail thread Orion started | Text from the person’s own address, with an opt-out line and sender details | |
| A thread or invitation the person sends in LinkedIn | A card with the exact text and a link that opens the right place | |
| X | A direct message conversation | A card at first, then a direct message once a budget is set |
| A chat with someone you already know | A card with the text and a link to the chat. A business number can use approved templates on Meta’s official route | |
| A direct message thread | A card with the exact text. A Professional account can reply on the official route, to people who wrote first | |
| A Page conversation, started by the person who wrote | A reply sent as the Page, when Meta allows it | |
| Telegram | A chat with someone you already know | A card with the text and a link to the chat |
| State | What it means |
|---|---|
| Preparing | Permission, identity, capability and content are being checked |
| Queued or held | Waiting its turn, or held by a limit or a pause. It is checked again before it goes |
| Accepted | The provider took it. This is not proof of delivery |
| Delivered or read | Shown only where that channel gives a verified signal |
| Reported | On a You send channel, the person said they sent it |
| Rejected | A definite refusal. A person reviews it |
| Outcome unknown | The response was lost. Orion looks it up and never resends blindly |
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.
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 betaCalendar 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.
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 betaEvery 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.
| Event | When it fires |
|---|---|
| account.connected | A real check passed on a newly linked account |
| account.needs_reconnect | The provider refused the account |
| account.health_changed | An account moved to Watch, Paused or back to Healthy |
| message.accepted | A provider accepted a message |
| message.bounced | A delivery report says the message failed |
| message.outcome_unknown | A response was lost, and Orion is looking it up |
| reply.received | A reply arrived in a conversation Orion started |
| reply.reported | A person said someone replied on a You send channel |
| person.opted_out | Someone asked not to be contacted. This holds for good |
| outreach.stopped | Outreach to a person stopped on every channel |
| meeting.booked | A meeting landed on the person’s calendar |
| meeting.moved | The time of an existing meeting changed |
| Channel | Signal into Orion |
|---|---|
| Gmail | Google’s push notifications, with a history cursor to recover from a gap |
| Other mailboxes | Polling, with server cursors to recover from a gap |
| X | X’s webhooks, once a budget is set |
| WhatsApp Business, Instagram Professional, Facebook Pages | Meta’s webhooks on their official routes |
| Telegram | Bot webhooks, or the update stream for a user account |
| Google Calendar | Watch channels, with sync tokens to recover from a gap |
| LinkedIn and personal WhatsApp or Instagram | The person’s tap. No provider signal is permitted |
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.
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
BetaEvery 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.
| Scope | What it allows | Status |
|---|---|---|
| read | Your saved campaigns and the people on them | Beta |
| draft | Prepare campaign drafts and add people to them | Beta |
| messages.read | The text of your Orion conversations, with separate consent for each account | Private beta |
| calendar.read | Your calendar, with separate consent | Private beta |
Limits and errors
Private betaLimits 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.
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.