Analytics API

Track and analyze your email campaign performance with detailed metrics and insights.

Get Campaign Analytics

Retrieve detailed analytics for a specific campaign.

Endpoint

GET /api/analytics/campaigns/:id

Example Request

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

Example Response

{
  "success": true,
  "data": {
    "campaign_id": "campaign_123",
    "campaign_name": "March Newsletter",
    "sent_at": "2025-03-01T10:00:00Z",
    "stats": {
      "sent": 1500,
      "delivered": 1495,
      "opened": 450,
      "clicked": 120,
      "bounced": 5,
      "complained": 1,
      "unsubscribed": 2,
      "unique_opens": 420,
      "unique_clicks": 100
    },
    "rates": {
      "delivery_rate": 99.67,
      "open_rate": 30.1,
      "click_rate": 8.0,
      "click_to_open_rate": 26.67,
      "bounce_rate": 0.33,
      "unsubscribe_rate": 0.13
    },
    "engagement_over_time": [
      {
        "hour": 0,
        "opens": 120,
        "clicks": 35
      },
      {
        "hour": 1,
        "opens": 85,
        "clicks": 22
      }
    ],
    "top_links": [
      {
        "url": "https://postbeagle.com/features",
        "clicks": 45,
        "unique_clicks": 38
      },
      {
        "url": "https://postbeagle.com/pricing",
        "clicks": 32,
        "unique_clicks": 28
      }
    ],
    "device_breakdown": {
      "desktop": 720,
      "mobile": 580,
      "tablet": 195
    },
    "client_breakdown": {
      "gmail": 550,
      "outlook": 320,
      "apple_mail": 280,
      "other": 345
    }
  }
}

Get Account Overview

Get account-wide analytics and performance metrics.

Endpoint

GET /api/analytics/overview

Query Parameters

Parameter	Type	Description	Default
`start_date`	string	Start date (ISO 8601)	30 days ago
`end_date`	string	End date (ISO 8601)	today

Example Request

curl -X GET "https://api.postbeagle.com/api/analytics/overview?start_date=2025-01-01&end_date=2025-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Response

{
  "success": true,
  "data": {
    "date_range": {
      "start": "2025-01-01T00:00:00Z",
      "end": "2025-01-31T23:59:59Z"
    },
    "summary": {
      "campaigns_sent": 12,
      "emails_sent": 18500,
      "emails_delivered": 18350,
      "emails_opened": 5505,
      "emails_clicked": 1480,
      "emails_bounced": 150,
      "emails_complained": 15,
      "emails_unsubscribed": 37
    },
    "average_rates": {
      "delivery_rate": 99.19,
      "open_rate": 29.78,
      "click_rate": 8.0,
      "bounce_rate": 0.81,
      "unsubscribe_rate": 0.2
    },
    "trends": [
      {
        "date": "2025-01-01",
        "sent": 1200,
        "opened": 360,
        "clicked": 96
      },
      {
        "date": "2025-01-02",
        "sent": 0,
        "opened": 45,
        "clicked": 12
      }
    ],
    "top_campaigns": [
      {
        "id": "campaign_123",
        "name": "New Year Newsletter",
        "sent": 2000,
        "open_rate": 35.5,
        "click_rate": 10.2
      }
    ],
    "audience_growth": {
      "contacts_added": 245,
      "contacts_unsubscribed": 37,
      "net_growth": 208,
      "growth_rate": 2.1
    }
  }
}

Get Contact Activity

View activity history for a specific contact.

Endpoint

GET /api/analytics/contacts/:id/activity

Query Parameters

Parameter	Type	Description	Default
`limit`	integer	Number of activities to return	50
`event_type`	string	Filter by event: `open`, `click`, `bounce`, `unsubscribe`	all

Example Request

curl -X GET "https://api.postbeagle.com/api/analytics/contacts/contact_123/activity?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Response

{
  "success": true,
  "data": {
    "contact_id": "contact_123",
    "email": "[email protected]",
    "activities": [
      {
        "event_type": "click",
        "campaign_id": "campaign_456",
        "campaign_name": "March Newsletter",
        "url": "https://postbeagle.com/features",
        "timestamp": "2025-03-01T11:30:00Z",
        "device": "mobile",
        "client": "gmail"
      },
      {
        "event_type": "open",
        "campaign_id": "campaign_456",
        "campaign_name": "March Newsletter",
        "timestamp": "2025-03-01T11:00:00Z",
        "device": "mobile",
        "client": "gmail"
      }
    ],
    "summary": {
      "total_campaigns_received": 25,
      "total_opens": 18,
      "total_clicks": 12,
      "last_activity": "2025-03-01T11:30:00Z"
    }
  }
}

Get Link Analytics

Track performance of specific links across campaigns.

Endpoint

GET /api/analytics/links

Query Parameters

Parameter	Type	Description	Default
`campaign_id`	string	Filter by specific campaign	all campaigns
`sort`	string	Sort by: `clicks`, `unique_clicks`	`-clicks`
`limit`	integer	Number of links to return	20

Example Request

curl -X GET "https://api.postbeagle.com/api/analytics/links?campaign_id=campaign_123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Response

{
  "success": true,
  "data": [
    {
      "url": "https://postbeagle.com/features",
      "short_url": "https://pb.link/abc123",
      "campaigns": ["campaign_123"],
      "total_clicks": 245,
      "unique_clicks": 198,
      "click_rate": 13.2,
      "top_locations": [
        {"country": "US", "clicks": 120},
        {"country": "UK", "clicks": 65}
      ],
      "device_breakdown": {
        "desktop": 145,
        "mobile": 85,
        "tablet": 15
      }
    }
  ]
}

Export Analytics

Export campaign analytics data as CSV or JSON.

Endpoint

GET /api/analytics/campaigns/:id/export

Query Parameters

Parameter	Type	Description	Default
`format`	string	Export format: `csv`, `json`	`json`
`include`	string	Data to include: `recipients`, `opens`, `clicks`, `all`	`all`

Example Request

curl -X GET "https://api.postbeagle.com/api/analytics/campaigns/campaign_123/export?format=csv" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output campaign_analytics.csv

Real-time Stats

Get real-time statistics for recently sent campaigns.

Endpoint

GET /api/analytics/realtime

Example Request

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

Example Response

{
  "success": true,
  "data": {
    "active_campaigns": [
      {
        "id": "campaign_789",
        "name": "Flash Sale",
        "sent_at": "2025-03-15T14:00:00Z",
        "stats": {
          "sent": 5000,
          "opened": 1250,
          "clicked": 320,
          "open_rate": 25.0,
          "click_rate": 6.4
        },
        "recent_activity": {
          "last_5_minutes": {
            "opens": 12,
            "clicks": 3
          }
        }
      }
    ]
  }
}

Engagement Heatmap

Get hour-by-hour engagement data to optimize send times.

Endpoint

GET /api/analytics/engagement-heatmap

Query Parameters

Parameter	Type	Description	Default
`days`	integer	Number of days to analyze	30

Example Response

{
  "success": true,
  "data": {
    "heatmap": [
      {
        "day": "monday",
        "hours": [
          {"hour": 0, "open_rate": 15.2, "click_rate": 3.1},
          {"hour": 1, "open_rate": 12.8, "click_rate": 2.5},
          {"hour": 9, "open_rate": 32.5, "click_rate": 8.2}
        ]
      }
    ],
    "best_send_times": [
      {"day": "tuesday", "hour": 10, "avg_open_rate": 35.8},
      {"day": "wednesday", "hour": 14, "avg_open_rate": 34.2}
    ]
  }
}

Code Examples

JavaScript

// Get campaign analytics
async function getCampaignAnalytics(campaignId) {
  const response = await fetch(
    `https://api.postbeagle.com/api/analytics/campaigns/${campaignId}`,
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      }
    }
  );
  return await response.json();
}

// Get account overview for date range
async function getAccountOverview(startDate, endDate) {
  const params = new URLSearchParams({
    start_date: startDate,
    end_date: endDate
  });
  
  const response = await fetch(
    `https://api.postbeagle.com/api/analytics/overview?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      }
    }
  );
  return await response.json();
}

Python

import requests
from datetime import datetime, timedelta

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

def get_monthly_overview():
    end_date = datetime.now()
    start_date = end_date - timedelta(days=30)
    
    url = 'https://api.postbeagle.com/api/analytics/overview'
    params = {
        'start_date': start_date.isoformat(),
        'end_date': end_date.isoformat()
    }
    headers = {
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    }
    
    response = requests.get(url, params=params, headers=headers)
    return response.json()

Metrics Glossary

Delivery Metrics

Sent: Total number of emails sent
Delivered: Emails successfully delivered to inbox
Bounced: Emails that failed to deliver (hard/soft bounces)

Engagement Metrics

Opens: Number of times emails were opened
Unique Opens: Number of individual recipients who opened
Clicks: Number of times links were clicked
Unique Clicks: Number of individual recipients who clicked

Rate Calculations

Delivery Rate: (Delivered / Sent) × 100
Open Rate: (Unique Opens / Delivered) × 100
Click Rate: (Unique Clicks / Delivered) × 100
Click-to-Open Rate: (Unique Clicks / Unique Opens) × 100

Best Practices

Track All Campaigns: Monitor performance to identify trends
Compare Metrics: Benchmark against industry averages
A/B Testing: Test subject lines and content
Optimize Send Times: Use heatmap data for timing
Monitor Bounces: Clean your list regularly
Link Tracking: Use meaningful UTM parameters
Export Data: Regularly export for long-term analysis

Next Steps

Campaigns API - Create and send campaigns
Contacts API - Manage your audience