Getting started

Introduction

Use the AutoWorkx Public API to build and manage integrations — manage leads and campaigns, read analytics, and send email from your own backend or integration.

What you can build

• Create, list and update leads, with automatic dedup by email.
• Create and manage campaigns, and start/pause/resume/stop them.
• Read account-wide and per-campaign analytics.
• Send or schedule one-off emails, and read outbox/inbox history.

Before you start

You need an AutoWorkx account and an API key. Create one from the API Keys page — when you create a key, select only the scopes your integration requires. Then follow the quickstart below to send your first request.

Prefer to import this into Postman, Insomnia, or generate a client? Download the OpenAPI 3.0 spec.

Getting started

Quickstart

Create an API key and make your first request in a few minutes.

1

Create an API key

Open the API Keys page and create a key. Select only the scopes your integration needs. Copy the key when it's displayed — you cannot view it again afterward.

2

Send your first request

Create a lead using your new API key:

cURLJavaScriptPython

Copy

curl -X POST "https://api.outbird.dev/v1/leads" \
  -H "Authorization: Bearer aw_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"leads":[{"email":"jane@acme.com","name":"Jane Doe"}]}'

Replace the placeholder with the key you created. A successful request returns a JSON response describing what was created.

3
Handle errors
Check the HTTP status code before processing the response:
• 400Validation failure — malformed input or a missing required field.
• 401The API key is missing, invalid, expired, or doesn't have the required scope.
• 404The resource doesn't exist, or isn't owned by this key's account.
• 429Per-key rate limit exceeded — honor the Retry-After header before retrying.

Getting started

Authentication

Every request is authenticated with your API key as a bearer token:

Authorization: Bearer aw_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Keep your API key secure. Never expose it in client-side code or commit it to source control. There is no session, no cookie, and no CORS on this API.

Getting started

Scopes

When you create a key, select only the scopes your integration requires.

A request with a key missing the required scope is rejected before your integration's logic ever runs.

Getting started

Rate limits

Requests are limited both per key and across your whole account.

Build exponential backoff into any automated integration. When the per-key limit is hit, every endpoint returns a real 429 with {"error":{"code":"RATE_LIMITED","message":"...","retryAfterSeconds":60}} and a Retry-After: 60 response header — honor that header before retrying rather than retrying immediately or on a fixed short interval.

API reference

Data models

Shared object shapes returned across multiple endpoints.

API reference

Leads

curl -X POST "https://api.outbird.dev/v1/leads" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "leads": [
    { "email": "jane@acme.com", "name": "Jane Doe", "company": "Acme", "phone": "+1234567890" }
  ],
  "campaignId": "optional-existing-campaign-id",
  "forceUpdate": false
}'

curl -X GET "https://api.outbird.dev/v1/leads" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY"

curl -X GET "https://api.outbird.dev/v1/leads/{id}" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY"

{ "lead": { "leadId": "...", "email": "jane@acme.com", "..." : "..." } }

curl -X PATCH "https://api.outbird.dev/v1/leads/{id}" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "New Name", "phone": "+1...", "company": "...", "location": "...",
  "linkedin": "...", "website": "...", "leadType": "...", "metadata": { "custom_field": "x" } }'

API reference

Campaigns

curl -X POST "https://api.outbird.dev/v1/campaigns" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Q3 Outreach",
  "campaignType": "AUTOMATION",
  "campaignMoto": "OUTREACH",
  "campaignTag": "",
  "trigger": { "type": "IMMEDIATE" },
  "schedule": { "days": ["MON","TUE","WED","THU","FRI"], "dailyLimit": 100,
                "timeWindow": { "start": "09:00", "end": "18:00" } },
  "campaignQuestions": {},
  "emailIndex": "you@yourdomain.com"
}'

curl -X GET "https://api.outbird.dev/v1/campaigns" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY"

curl -X GET "https://api.outbird.dev/v1/campaigns/{id}" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY"

curl -X PATCH "https://api.outbird.dev/v1/campaigns/{id}" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY"

curl -X POST "https://api.outbird.dev/v1/campaigns/{id}/start" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY"

curl -X POST "https://api.outbird.dev/v1/campaigns/{id}/pause" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY"

curl -X POST "https://api.outbird.dev/v1/campaigns/{id}/resume" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY"

curl -X POST "https://api.outbird.dev/v1/campaigns/{id}/stop" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY"

API reference

Analytics

curl -X GET "https://api.outbird.dev/v1/analytics" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY"

{
  "analytics": { "emailsSent":0,"opens":0,"uniqueOpens":0,"clicks":0,"uniqueClicks":0,
    "replies":0,"bounces":0,"unsubscribes":0,"lastActivityAt":null },
  "emailStats": { "total":0,"scheduled":0,"sent":0,"failed":0,"stopped":0,
    "generationFailed":0,"lowScore":0,"opened":0,"clicked":0,"replied":0,"bounced":0,
    "unsubscribed":0 },
  "usage": { "containerCount":1,"leadCount":2 }
}

curl -X GET "https://api.outbird.dev/v1/campaigns/{id}/analytics" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY"

{ "campaignId":"...", "name":"...", "status":"...", "analytics": {"...":"..."}, "usage": {"leadCount":1} }

API reference

Emails (outbox + inbox + send)

curl -X GET "https://api.outbird.dev/v1/emails" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY"

curl -X GET "https://api.outbird.dev/v1/emails/{id}" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY"

curl -X POST "https://api.outbird.dev/v1/emails/send" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "jane@acme.com",
  "subject": "Quick question",
  "html": "<p>Hi Jane...</p>",
  "emailIndex": "your-connected@gmail.com",
  "tag": "api-outreach",
  "leadId": "optional-lead-id",
  "scheduleAt": "2026-09-01T10:00:00.000Z"
}'

API reference

Account

curl -X GET "https://api.outbird.dev/v1/me" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY"

{
  "userId": "...", "email": "...", "name": "...",
  "company_website": "https://...", "company_intelligence": { "...": "..." },
  "emailConnect": [ { "email": "...", "displayName": "..." } ],
  "usage": { "containerCount": 1, "leadCount": 2 }, "acceptedTerms": true
}

curl -X POST "https://api.outbird.dev/v1/company" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com" }'

API reference

Email Accounts

Connect/list/disconnect the sending mailboxes used by POST /v1/emails/send and emailIndex/followUpEmailIndex on campaigns. Credentials are live-verified against the real provider before anything is saved — a real SMTP login (+ a real test email send), then a real IMAP login. No plaintext password is ever returned in any response.

• Known SMTP/IMAP hosts are resolved automatically for gmail, outlook, zoho, and yahoo — you never need to supply smtpHost for those. zoho tries both smtp.zoho.in and smtp.zoho.com.
• gmail/outlook/yahoo/zoho require a provider app password, not your normal login password — every major provider requires 2FA to be enabled before it will issue one.
• Reconnecting the same address (e.g. after rotating an app password) is idempotent — it replaces the existing entry for that email rather than creating a duplicate.

curl -X POST "https://api.outbird.dev/v1/email-accounts" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "gmail", "email": "you@yourdomain.com", "password": "<app password>" }'

{ "message": "gmail account connected successfully", "email": "you@yourdomain.com", "totalAccounts": 2 }

curl -X GET "https://api.outbird.dev/v1/email-accounts" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY"

{ "emailAccounts": [ { "email": "...", "provider": "gmail", "displayName": "...", "smtpHost": "...", "smtpPort": 465, "imapHost": "...", "imapPort": 993, "connectedAt": "..." } ] }

curl -X DELETE "https://api.outbird.dev/v1/email-accounts/{email}" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY"

{ "email": "you@yourdomain.com", "status": "disconnected" }

API reference

Webhooks

Subscribe a URL to be notified in near-real-time when events happen on your account, instead of polling GET /v1/emails / GET /v1/campaigns/{id}. Delivery is asynchronous (via an internal queue) — expect a delay of a few seconds between the event happening and your endpoint receiving the POST, not instant delivery.

• Event types: campaign.started, campaign.paused, campaign.resumed, campaign.stopped, email.sent, email.opened, email.clicked, email.replied, email.bounced (or "*" to subscribe to all of them).
• Max 10 webhooks per account (400 WEBHOOK_LIMIT_REACHED beyond that).
• Your endpoint must respond with a 2xx status within 8 seconds, or the delivery is treated as failed. Failed deliveries are automatically retried (up to 5 attempts total with backoff); after that they are dropped.
• Every delivery carries a stable eventId (the SAME on every redelivery of one logical event) and a per-attempt deliveryId (different on every retry) — dedupe on eventId / X-AutoWorkx-Event-Id, since a delivery can still arrive more than once (retry, or two webhooks subscribed to "*" both matching).

{ "event": "email.sent", "eventId": "3fae2d1c-6c9e-4c1a-9c1a-2f0e6f6f6f6f", "deliveryId": "a1b2c3d4-...", "timestamp": "2026-08-24T08:48:23.964Z", "data": { "emailId": "...", "campaignId": "...", "leadId": "...", "to": "..." } }

const crypto = require("crypto");
const expected = "sha256=" + crypto.createHmac("sha256", YOUR_WEBHOOK_SECRET).update(rawBody).digest("hex");
if (expected !== req.headers["x-autoworkx-signature"]) return res.status(401).end();

curl -X POST "https://api.outbird.dev/v1/webhooks" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-server.example.com/webhooks/autoworkx", "events": ["email.sent", "campaign.started"] }'

{
  "webhookId": "...", "url": "...", "events": ["email.sent", "campaign.started"],
  "status": "active", "createdAt": "...",
  "secret": "<64 hex chars — SHOWN ONLY THIS ONCE>",
  "warning": "Store this secret now — it will not be shown again. Use it to verify the X-AutoWorkx-Signature header on incoming deliveries."
}

curl -X GET "https://api.outbird.dev/v1/webhooks" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY"

{ "webhooks": [ { "webhookId": "...", "url": "...", "events": ["..."], "status": "active", "secretPrefix": "..." } ] }

curl -X DELETE "https://api.outbird.dev/v1/webhooks/{id}" \
  -H "Authorization: Bearer aw_live_YOUR_API_KEY"

{ "webhookId": "...", "status": "deleted" }

API reference

Status codes

Every HTTP status code returned anywhere in this API.

Quick reference