Outbird

Outbird Public API

Getting started

Introduction

Use the Outbird 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 or stop them.
  • Read account-wide and per-campaign analytics.
  • Send or schedule one-off emails, and read outbox and inbox history.

Before you start

You need an Outbird 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 or 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 is displayed — you cannot view it again afterward.

    2

    Send your first request

    Create a lead using your new API key:

    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
HeaderRequiredNotes
AuthorizationYesBearer <apiKey> — the only supported auth mechanism
X-Api-KeyFallback onlyAccepted if Authorization can't be set by your tooling; prefer Authorization
Content-TypeFor POST/PATCH bodiesapplication/json required on any request with a JSON body

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.

ScopeRequired for
leads:readGET /v1/leads, GET /v1/leads/{id}
leads:writePOST /v1/leads, PATCH /v1/leads/{id}
campaigns:readGET /v1/campaigns, GET /v1/campaigns/{id}
campaigns:writePOST /v1/campaigns, PATCH /v1/campaigns/{id}
campaigns:startPOST /v1/campaigns/{id}/{start|pause|resume|stop}
analytics:readGET /v1/analytics, GET /v1/campaigns/{id}/analytics
emails:readGET /v1/emails, GET /v1/emails/{id}
emails:sendPOST /v1/emails/send
account:readGET /v1/me
account:writePOST /v1/company
webhooks:readGET /v1/webhooks
webhooks:writePOST /v1/webhooks, DELETE /v1/webhooks/{id}

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.

LayerLimitScope
Per-API-key60 requests / minute (default)Each individual key has its own independent budget
Stage-wide (API Gateway)25 requests/sec steady-state, burst 50Shared across all keys combined

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