Agent & API Documentation

AI Outbound OS is built to be operated programmatically. Add cold leads, organize them, generate AI-personalized copy, build sequences, and launch campaigns — all without the UI, via the MCP server or the REST API.

Overview

There are two equivalent surfaces, both authenticated with the same workspace API key:

  • POST /api/mcp — Model Context Protocol (JSON-RPC 2.0). Best for LLM agents like Claude.
  • /api/v1/* — plain JSON REST. Best for scripts and backends.

They share the same underlying logic, so behaviour is identical.

Authentication

Generate a key in the dashboard: Settings → API & MCP Access → Generate. The raw key (aiob_…) is shown once. Send it as a Bearer token on every request:

Authorization: Bearer aiob_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Each key is scoped to exactly one workspace.

Connect an MCP client

For Claude Desktop or Claude Code, add to your MCP config:

{
  "mcpServers": {
    "ai-outbound": {
      "url": "https://outbound.malecu.eu/api/mcp",
      "headers": { "Authorization": "Bearer aiob_..." }
    }
  }
}

GET /api/mcp returns a live capability document (tool list + workflow) you can fetch anytime.

The end-to-end workflow

An agent runs the whole pipeline with these calls in order:

  1. create_group — define an audience
  2. add_leads — import leads (assign to groups inline)
  3. create_variable — define an AI personalization prompt
  4. generate_variables — fill it across all leads (async)
  5. create_sequence — build the email steps
  6. preview_email — verify copy for a sample lead
  7. list_senders / list_campaigns — discover sending infra
  8. launch_sequence — start sending (native or instantly)
  9. get_run_status / control_run — monitor & control

Variable generation and runs are asynchronous — poll list_variables (pct) and get_run_status for progress.

MCP tools (24)

Leads

add_leadsAdd/update leads (dedupe by email); assign to groups inline
query_leadsSearch & filter leads, paginated
get_leadOne lead + variable values + group memberships
update_leadUpdate fields on a lead
delete_leadPermanently delete a lead and its variable values
export_leadsExport leads with all variable values as columns

Groups

list_groupsAll groups with lead counts
create_groupCreate a named audience
update_groupRename or recolor a group
delete_groupDelete a group (leads are kept)
add_leads_to_groupAdd existing leads to a group

Variables (AI personalization)

list_variablesDefinitions + generation progress
create_variableDefine an AI prompt template
generate_variablesGenerate values across leads (async)

Sequences

list_sequencesSequences with step counts
get_sequenceFull sequence with steps
create_sequenceBuild a multi-step email sequence
preview_emailRender a step for a lead

Sending infrastructure

list_campaignsInstantly campaigns
list_sendersInstantly accounts + Resend domains

Launch & monitor

launch_sequenceStart a run (native or instantly)
list_runsList runs by status
get_run_statusRun progress + recent logs
control_runStop / pause / resume a run

REST API

Base URL /api/v1. Responses are { data, meta? } on success, { error } on failure.

POST   /leads                  upsert lead or array; accepts groups:[names]
GET    /leads?group_id=&search=&page=&limit=
GET    /leads/:id
PATCH  /leads/:id
DELETE /leads/:id
GET    /leads/export?group_id=&search=&limit=

GET    /groups
POST   /groups                 { name, color?, description? }
PATCH  /groups/:id             { name?, color?, description? }
DELETE /groups/:id
POST   /groups/:id             { lead_ids: [...] }   ← add members

GET    /variables
POST   /variables              { name, prompt_template, output_type? }
POST   /variables/:name/generate

GET    /sequences
POST   /sequences              { name, description?, steps: [...] }
GET    /sequences/:id

GET    /runs?status=
POST   /runs                   { engine, sequence_id|campaign_id, sender_email, group_id? }
GET    /runs/:id
POST   /runs/:id/stop | /pause | /resume

Example — full pipeline with curl

KEY="aiob_..."
BASE="https://outbound.malecu.eu/api/v1"

# 1. Create a group
GID=$(curl -s -X POST $BASE/groups -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"London Agencies","color":"emerald"}' | jq -r .data.id)

# 2. Add leads into it
curl -s -X POST $BASE/leads -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '[{"email":"jo@acme.com","first_name":"Jo","company_name":"Acme","groups":["London Agencies"]}]'

# 3. Launch a native sequence to that group
curl -s -X POST $BASE/runs -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d "{\"engine\":\"native\",\"sequence_id\":\"SEQ_UUID\",\"sender_email\":\"hi@you.com\",\"group_id\":\"$GID\"}"
Need a key? Sign in and open Settings → API & MCP Access.