API Overview

The PostBeagle API provides programmatic access to all core features of the platform. Build integrations, automate workflows, and manage your email marketing campaigns via REST API.

Base URL

All API requests should be made to:

https://api.postbeagle.com/api

Authentication

All API requests require authentication via API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

See the Authentication guide for details.

Request Format

Headers

All requests should include these headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Body

Send data as JSON in the request body:

{
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe"
}

Response Format

Success Response

Successful requests return a JSON response with relevant data:

{
  "success": true,
  "data": {
    "id": "contact_123",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe"
  }
}

Error Response

Failed requests return an error object:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email address",
    "details": {
      "field": "email",
      "reason": "Invalid format"
    }
  }
}

HTTP Status Codes

Rate Limiting

The API is rate limited to ensure fair usage:

• 100 requests per minute per API key
• 10 requests per second burst limit

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

Pagination

List endpoints support pagination using query parameters:

GET /v1/contacts?page=1&limit=50

Parameters:

• page - Page number (default: 1)
• limit - Items per page (default: 20, max: 100)

Response includes pagination metadata:

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Filtering & Sorting

Filtering

Filter results using query parameters:

GET /v1/contacts?status=subscribed&tags=customer

Sorting

Sort results using the sort parameter:

GET /v1/contacts?sort=-created_at

Use - prefix for descending order.

Available Endpoints

Account

GET    /api/account           Get account information
PUT    /api/account           Update account settings

Contacts

GET    /api/contacts          List all contacts
POST   /api/contacts          Create a new contact
GET    /api/contacts/:id      Get contact details
PUT    /api/contacts/:id      Update a contact
DELETE /api/contacts/:id      Delete a contact
POST   /api/contacts/import   Import contacts in bulk

Email Lists

GET    /api/email-lists                List all email lists
GET    /api/email-lists/stats          Get list statistics
GET    /api/email-lists/:id            Get list details
GET    /api/email-lists/:id/contacts   Get contacts in list
POST   /api/email-lists                Create a new list
PUT    /api/email-lists/:id            Update a list
DELETE /api/email-lists/:id            Delete a list
POST   /api/email-lists/:id/contacts   Add contacts to list

Segments

GET    /api/segments                   List all segments
GET    /api/segments/:id               Get segment details
POST   /api/segments                   Create a new segment
PUT    /api/segments/:id               Update a segment
DELETE /api/segments/:id               Delete a segment
POST   /api/segments/_preview          Preview segment matches
GET    /api/segments/:id/contacts      Get segment contacts

Landing Pages

GET    /api/landing-pages                  List all landing pages
GET    /api/landing-pages/:id              Get landing page details
POST   /api/landing-pages                  Create landing page
POST   /api/landing-pages/:id/save-settings    Save settings
POST   /api/landing-pages/:id/save-design      Save design
POST   /api/landing-pages/:id/publish          Publish page
DELETE /api/landing-pages/:id              Delete landing page

Popup Forms

GET    /api/popup-forms                    List all popup forms
GET    /api/popup-forms/:id                Get popup form details
POST   /api/popup-forms                    Create popup form
POST   /api/popup-forms/:id/save-settings      Save settings
POST   /api/popup-forms/:id/save-design        Save design
POST   /api/popup-forms/:id/publish            Publish/unpublish
POST   /api/popup-forms/:id/duplicate          Duplicate form
DELETE /api/popup-forms/:id                Delete popup form

Campaigns

GET    /api/campaigns         List all campaigns
POST   /api/campaigns         Create a new campaign
GET    /api/campaigns/:id     Get campaign details
PUT    /api/campaigns/:id     Update a campaign
DELETE /api/campaigns/:id     Delete a campaign
POST   /api/campaigns/:id/send   Send a campaign

Analytics

GET    /api/analytics/campaigns/:id    Get campaign analytics
GET    /api/analytics/overview         Get account-wide analytics

Code Examples

JavaScript/Node.js

const apiKey = process.env.POSTBEAGLE_API_KEY;
const baseUrl = 'https://api.postbeagle.com/api';

async function getContacts() {
  const response = await fetch(`${baseUrl}/contacts`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    }
  });
  
  return await response.json();
}

Python

import os
import requests

api_key = os.environ['POSTBEAGLE_API_KEY']
base_url = 'https://api.postbeagle.com/api'

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

response = requests.get(f'{base_url}/contacts', headers=headers)
contacts = response.json()

cURL

curl -X GET https://api.postbeagle.com/api/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Webhooks

PostBeagle can send webhook events for important activities:

• contact.created - New contact added
• contact.unsubscribed - Contact unsubscribed
• campaign.sent - Campaign sent successfully
• campaign.opened - Campaign opened by recipient
• campaign.clicked - Link clicked in campaign

Configure webhooks in Settings → Webhooks.

Testing

Use a test mode for safe development:

X-Test-Mode: true

Test mode prevents actual emails from being sent.

Support

Need help? Check out:

• Authentication Guide
• Contact Management
• Email Lists
• Segments
• Landing Pages
• Popup Forms
• Campaign API
• Analytics API

Changelog

v1.0 (Current)

• Initial API release
• Contact management endpoints
• Campaign creation and sending
• Analytics and reporting
• Webhook support