API Reference

Base URL

https://api.bitelio.com

Every request goes to this base URL.

Authentication

Pass your API key as a bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

• Secret Key (sk_*) — needed everywhere except /v1/track
• Public Key (pk_*) — accepted solely by /v1/track, so you can track events from client-side code

Making requests

Send transactional email

curl -X POST https://api.bitelio.com/v1/send \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Hello",
    "body": "<p>Your message here</p>"
  }'

Track event

curl -X POST https://api.bitelio.com/v1/track \
  -H "Authorization: Bearer pk_your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "event": "signed_up"
  }'

Create contact

curl -X POST https://api.bitelio.com/contacts \
  -H "Authorization: Bearer sk_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "subscribed": true,
    "data": {
      "firstName": "John",
      "plan": "pro"
    }
  }'

Response format

Success responses

The public endpoints (/v1/send, /v1/track, /v1/verify) wrap their payload in an envelope:

{
  "success": true,
  "data": {
    "contact": "cnt_abc123",
    "event": "evt_xyz789",
    "timestamp": "2025-11-30T10:30:00.000Z"
  }
}

Dashboard-style endpoints (contacts, templates, campaigns, segments, workflows, and so on) skip the success/data envelope and hand back the resource itself:

{
  "id": "cnt_abc123",
  "email": "user@example.com",
  "createdAt": "2025-11-30T10:30:00.000Z"
}

Cursor-paginated list endpoints respond with:

{
  "data": [ /* items */ ],
  "cursor": "def456",
  "hasMore": true,
  "total": 10000
}

Error response

Every error carries enough detail to debug it directly:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "statusCode": 422,
    "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "errors": [
      {
        "field": "email",
        "message": "Invalid email",
        "code": "invalid_string"
      }
    ],
    "suggestion": "One or more fields have incorrect types. Check that strings are quoted, numbers are unquoted, and booleans are true/false."
  },
  "timestamp": "2025-11-30T10:30:00.000Z"
}

Error fields:

• code — stable, machine-readable identifier you can branch on in code
• message — plain-language explanation of the failure
• statusCode — the HTTP status
• requestId — unique per request; quote it when you write to support
• errors — per-field validation breakdown, present when relevant
• suggestion — a hint on how to resolve the problem

The Error Codes documentation covers every code with worked examples.

Pagination

Cursor-based pagination is the norm for list endpoints:

GET /contacts?limit=100&cursor=abc123

Parameters:

• limit — page size (default: 20, max: 100)
• cursor — the cursor value returned by the previous page

Response:

{
  "data": [ /* items */ ],
  "cursor": "def456",
  "hasMore": true,
  "total": 10000
}

Feed each response's cursor into the next request's cursor query parameter, and stop once hasMore comes back false. Only the first page (the one fetched without a cursor) computes total; later pages report total: 0 so listing stays fast.

A handful of endpoints (e.g. GET /segments/:id/contacts) paginate by page number instead, taking page and pageSize and returning total, page, and pageSize in the response.

Rate limits

To keep the service healthy for everyone, Bitelio applies sensible limits:

• Email sending — throttled per project to protect deliverability.
• API requests — 1000 requests/minute per project.
• Bulk operations — automatically queued for asynchronous processing.

Crossing a limit gets you a 429 Too Many Requests response.

Error codes

Errors combine standard HTTP status codes with machine-readable code identifiers:

400 Bad Request — Parameters are invalid or the request body is malformed

401 Unauthorized — API key absent or not valid

403 Forbidden — You lack access to the resource, or the project is disabled

404 Not Found — No such resource

422 Unprocessable Entity — Validation rejected the request (the errors array explains why)

429 Too Many Requests — You've hit a rate limit

500 Internal Server Error — Something failed on our side (send support the request ID)

The full catalogue, with troubleshooting steps, lives in the Error Codes documentation.

API endpoints

Every endpoint the Bitelio API exposes, grouped by resource.

Public API

The /v1/* routes exist for your application code and take flat, denormalised payloads. Of all endpoints, only POST /v1/track accepts a public (pk_*) key.

Contacts

Templates

Campaigns

Segments

Workflows

A workflow is stored as a workflow record plus a graph of steps, the transitions connecting them, and one execution per contact passing through. The endpoints follow that same structure.

Events

Domains

Activity & analytics

Uploads

Authentication & user management

These routes back the dashboard, which signs in with JWT cookies. They rarely matter for server-to-server work, but the list is included so nothing is undocumented.

API keys

Scoped secret keys, per project. See the API Keys guide for the permission catalog and creation rules. All three require a signed-in dashboard session with the apikeys:manage permission — none can be called with an API key.

Configuration

Internal webhook endpoints

The email and billing infrastructure delivers its events here. Your applications never call these — they appear only so the list is complete.

Client libraries

Node.js

const BITELIO_SECRET_KEY = process.env.BITELIO_SECRET_KEY;

async function sendEmail(to, subject, body) {
  const response = await fetch('https://api.bitelio.com/v1/send', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${BITELIO_SECRET_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ to, subject, body })
  });

  const data = await response.json();

  if (!data.success) {
    throw new Error(`[${data.error.code}] ${data.error.message}`);
  }

  return data.data;
}

Python

import os
import requests

BITELIO_SECRET_KEY = os.environ['BITELIO_SECRET_KEY']

def send_email(to, subject, body):
    response = requests.post(
        'https://api.bitelio.com/v1/send',
        headers={
            'Authorization': f'Bearer {BITELIO_SECRET_KEY}',
            'Content-Type': 'application/json'
        },
        json={'to': to, 'subject': subject, 'body': body}
    )

    data = response.json()

    if not data.get('success'):
        error = data['error']
        raise Exception(f"[{error['code']}] {error['message']}")

    return data['data']

cURL

curl -X POST https://api.bitelio.com/v1/send \
  -H "Authorization: Bearer $BITELIO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "user@example.com", "subject": "Hello", "body": "Message"}'

What's next

• Send a transactional email
• Track an event
• Error codes reference