Campaigns API

Create, manage, and send email campaigns programmatically.

List Campaigns

Retrieve a list of all campaigns.

Endpoint

GET /api/campaigns

Query Parameters

Example Request

curl -X GET "https://api.postbeagle.com/api/campaigns?status=sent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "campaign_123",
      "name": "March Newsletter",
      "subject": "Check out what's new!",
      "status": "sent",
      "recipients_count": 1500,
      "stats": {
        "sent": 1500,
        "opened": 450,
        "clicked": 120,
        "bounced": 5,
        "unsubscribed": 2
      },
      "sent_at": "2025-03-01T10:00:00Z",
      "created_at": "2025-02-28T15:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "pages": 3
  }
}

Get Campaign

Retrieve details for a specific campaign.

Endpoint

GET /api/campaigns/:id

Example Response

{
  "success": true,
  "data": {
    "id": "campaign_123",
    "name": "March Newsletter",
    "subject": "Check out what's new!",
    "preview_text": "Your monthly update from PostBeagle",
    "from_name": "PostBeagle Team",
    "from_email": "[email protected]",
    "reply_to": "[email protected]",
    "status": "sent",
    "html_content": "<html>...</html>",
    "text_content": "Plain text version...",
    "recipients": {
      "lists": ["list_456"],
      "tags": ["customer"],
      "count": 1500
    },
    "stats": {
      "sent": 1500,
      "delivered": 1495,
      "opened": 450,
      "clicked": 120,
      "bounced": 5,
      "complained": 1,
      "unsubscribed": 2,
      "open_rate": 30.1,
      "click_rate": 8.0
    },
    "sent_at": "2025-03-01T10:00:00Z",
    "created_at": "2025-02-28T15:30:00Z"
  }
}

Create Campaign

Create a new email campaign.

Endpoint

POST /api/campaigns

Request Body

Example Request

curl -X POST "https://api.postbeagle.com/api/campaigns" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "April Newsletter",
    "subject": "Spring Updates from PostBeagle",
    "preview_text": "New features and tips for better email marketing",
    "from_name": "PostBeagle Team",
    "from_email": "[email protected]",
    "reply_to": "[email protected]",
    "html_content": "<html><body><h1>Hello!</h1></body></html>",
    "text_content": "Hello! This is the plain text version.",
    "lists": ["list_456"]
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "campaign_789",
    "name": "April Newsletter",
    "subject": "Spring Updates from PostBeagle",
    "status": "draft",
    "created_at": "2025-04-01T09:00:00Z"
  }
}

Update Campaign

Update a draft campaign. Once sent, campaigns cannot be modified.

Endpoint

PUT /api/campaigns/:id

Example Request

curl -X PUT "https://api.postbeagle.com/api/campaigns/campaign_789" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Updated: Spring Updates from PostBeagle",
    "lists": ["list_456", "list_789"]
  }'

Delete Campaign

Delete a draft campaign. Sent campaigns cannot be deleted.

Endpoint

DELETE /api/campaigns/:id

Example Request

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

Send Campaign

Send a campaign immediately or schedule it for later.

Endpoint

POST /api/campaigns/:id/send

Request Body

Send Immediately

curl -X POST "https://api.postbeagle.com/api/campaigns/campaign_789/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Schedule for Later

curl -X POST "https://api.postbeagle.com/api/campaigns/campaign_789/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule_at": "2025-04-15T14:00:00Z"
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "campaign_789",
    "status": "sent",
    "recipients_count": 2000,
    "sent_at": "2025-04-01T10:30:00Z"
  }
}

Send Test Email

Send a test email before sending the campaign.

Endpoint

POST /api/campaigns/:id/test

Request Body

Example Request

curl -X POST "https://api.postbeagle.com/api/campaigns/campaign_789/test" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

Cancel Scheduled Campaign

Cancel a scheduled campaign before it sends.

Endpoint

POST /api/campaigns/:id/cancel

Example Request

curl -X POST "https://api.postbeagle.com/api/campaigns/campaign_789/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Error Responses

400 Bad Request - Invalid Recipients

{
  "success": false,
  "error": {
    "code": "INVALID_RECIPIENTS",
    "message": "No recipients specified. Add at least one list or tag."
  }
}

403 Forbidden - Unverified Sender

{
  "success": false,
  "error": {
    "code": "UNVERIFIED_SENDER",
    "message": "The sender email address is not verified"
  }
}

409 Conflict - Already Sent

{
  "success": false,
  "error": {
    "code": "ALREADY_SENT",
    "message": "This campaign has already been sent and cannot be modified"
  }
}

Code Examples

JavaScript

// Create and send a campaign
async function createAndSendCampaign() {
  // 1. Create the campaign
  const campaign = await fetch('https://api.postbeagle.com/api/campaigns', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Welcome Email',
      subject: 'Welcome to PostBeagle!',
      from_name: 'PostBeagle',
      from_email: '[email protected]',
      html_content: '<h1>Welcome!</h1><p>Thanks for joining.</p>',
      lists: ['list_456']
    })
  });
  
  const campaignData = await campaign.json();
  const campaignId = campaignData.data.id;
  
  // 2. Send a test email
  await fetch(`https://api.postbeagle.com/api/campaigns/${campaignId}/test`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email: '[email protected]'
    })
  });
  
  // 3. Send the campaign
  const send = await fetch(`https://api.postbeagle.com/api/campaigns/${campaignId}/send`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    }
  });
  
  return await send.json();
}

Python

import requests

def create_campaign(name, subject, html_content, lists):
    url = 'https://api.postbeagle.com/api/campaigns'
    headers = {
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    }
    data = {
        'name': name,
        'subject': subject,
        'from_name': 'PostBeagle',
        'from_email': '[email protected]',
        'html_content': html_content,
        'lists': lists
    }
    
    response = requests.post(url, json=data, headers=headers)
    return response.json()

def send_campaign(campaign_id):
    url = f'https://api.postbeagle.com/api/campaigns/{campaign_id}/send'
    headers = {
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    }
    
    response = requests.post(url, headers=headers)
    return response.json()

Best Practices

1. Test First: Always send test emails before sending to your list
2. Verify Senders: Ensure sender email addresses are verified
3. Segment Lists: Target specific audiences with lists and tags
4. Schedule Wisely: Send at optimal times for your audience
5. Monitor Stats: Track opens and clicks to improve future campaigns
6. Plain Text: Include plain text versions for better deliverability
7. Preview Text: Use preview text to increase open rates

Next Steps

• Analytics API - Track campaign performance
• Contacts API - Manage your recipients