Skip to main content
Access dashboard summaries, email performance metrics, and campaign engagement data using the API.

​
Goal

By the end of this guide you will be able to retrieve your dashboard summary statistics, view overall email performance, get time-series histograms, pull detailed reports for individual campaigns, and access engagement breakdowns.

​
Prerequisites

  • An API key with reports:read scope
  • Your API base URL (found on the Settings > API Keys page)
  • At least one sent campaign (for meaningful report data)

​
Steps

​
1. Get dashboard summary

Retrieve a high-level snapshot of your email and contact performance over a specified time period. 
curl "<your-api-base-url>/api/reports/dashboard?pastDays=30&timezone=America/New_York" \
  -H "X-API-Key: bme_us_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v"
Query parameters:
ParameterRequiredDescription
pastDaysYesNumber of days to look back (1-90)
timezoneNoIANA timezone code (default: UTC). Example: America/New_York, Europe/London
Response (200 OK): 
{
  "campaign": {
    "sent": {
      "count": 2379,
      "diff": 0.76
    },
    "delivered": {
      "count": 2203,
      "diff": 11.3
    },
    "uniqueOpens": {
      "count": {
        "value": 733,
        "diff": -23.41
      },
      "rate": {
        "value": 33.27,
        "diff": -22.41
      }
    },
    "uniqueClicks": {
      "count": {
        "value": 569,
        "diff": -21.52
      },
      "rate": {
        "value": 25.83,
        "diff": 20.47
      }
    }
  },
  "contact": {
    "count": {
      "value": 5900,
      "diff": 29.55
    },
    "histogram": {
      "start": "2026-02-28T00:00:00.000Z",
      "end": "2026-03-30T00:00:00.000Z",
      "histogram": [
        { "date": "2026-02-28T00:00:00.000Z", "total": 5420 },
        { "date": "2026-03-07T00:00:00.000Z", "total": 5580 },
        { "date": "2026-03-14T00:00:00.000Z", "total": 5710 },
        { "date": "2026-03-21T00:00:00.000Z", "total": 5850 },
        { "date": "2026-03-28T00:00:00.000Z", "total": 5900 }
      ],
      "peak": {
        "date": "2026-03-28T00:00:00.000Z",
        "total": 5900
      }
    }
  }
}
Understanding the diff field: The diff value is a percentage change compared to the equivalent preceding time period. For example, with pastDays=30, the diff compares the last 30 days to the 30 days before that. A positive value means an increase; negative means a decrease.

​
2. Get email performance overview

Retrieve aggregate email performance statistics across all campaigns. 
curl "<your-api-base-url>/api/reports/email/overall?pastDays=30&timezone=America/New_York" \
  -H "X-API-Key: bme_us_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v"
Response (200 OK): 
{
  "sent": 8450,
  "delivered": 8120,
  "opens": {
    "unique": 2890,
    "rate": 35.59
  },
  "clicks": {
    "unique": 1150,
    "rate": 14.16
  },
  "bounces": {
    "total": 330,
    "hard": 145,
    "soft": 185,
    "rate": 3.91
  },
  "unsubscribes": 42,
  "complaints": 3
}

​
3. Get email performance histogram

Retrieve a time-series breakdown of email performance for chart visualization. 
curl "<your-api-base-url>/api/reports/email/overall/histogram?pastDays=30&timezone=America/New_York" \
  -H "X-API-Key: bme_us_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v"
Response (200 OK): 
{
  "start": "2026-02-28T00:00:00.000Z",
  "end": "2026-03-30T00:00:00.000Z",
  "histogram": [
    {
      "date": "2026-03-01T00:00:00.000Z",
      "sent": 280,
      "delivered": 268,
      "opens": 95,
      "clicks": 38
    },
    {
      "date": "2026-03-08T00:00:00.000Z",
      "sent": 1250,
      "delivered": 1198,
      "opens": 425,
      "clicks": 170
    },
    {
      "date": "2026-03-15T00:00:00.000Z",
      "sent": 3400,
      "delivered": 3265,
      "opens": 1160,
      "clicks": 465
    }
  ]
}

​
4. Get campaign-specific report

Retrieve detailed performance metrics for a single campaign. You will need the campaign ID (from GET /api/email/campaign). 
curl "<your-api-base-url>/api/reports/email/66f1a6e4698f1bca60426002" \
  -H "X-API-Key: bme_us_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v"
Response (200 OK): 
{
  "stats": {
    "sent": 697,
    "delivered": 655,
    "opens": {
      "unique": 210,
      "last": "2026-03-27T17:33:45.464Z",
      "rate": 32.06
    },
    "clicks": {
      "unique": 169,
      "last": "2026-03-27T18:28:40.575Z",
      "rate": 25.8
    },
    "totalBounces": {
      "count": 42,
      "rate": 6.87
    },
    "hardBounces": {
      "count": 25,
      "rate": 3.81
    },
    "softBounces": {
      "count": 17,
      "rate": 2.59
    },
    "unsubscribes": 0,
    "complaints": 0
  },
  "linkActivity": [
    {
      "id": "66f1a6e4698f1bca60424808",
      "path": "https://mybusiness.com/spring-sale",
      "clicks": {
        "total": 145,
        "unique": 120
      }
    },
    {
      "id": "66f1a6e4698f1bca60424809",
      "path": "https://instagram.com/mybusiness",
      "clicks": {
        "total": 38,
        "unique": 32
      }
    }
  ]
}
Key metrics explained:
  • sent — Total emails dispatched
  • delivered — Emails that reached the recipient’s mail server
  • opens.unique — Number of unique recipients who opened the email
  • opens.rate — Open rate as a percentage of delivered emails
  • clicks.unique — Number of unique recipients who clicked a link
  • clicks.rate — Click rate as a percentage of delivered emails
  • totalBounces — Hard + soft bounces combined
  • hardBounces — Permanent delivery failures (invalid addresses)
  • softBounces — Temporary delivery failures (full mailbox, server issues)
  • linkActivity — Per-link click breakdown

​
5. Get campaign engagement details

Retrieve a time-series engagement histogram for a specific campaign, useful for understanding when recipients interact with your email. 
curl "<your-api-base-url>/api/reports/email/66f1a6e4698f1bca60426002/engagement?period=week&timezone=America/New_York" \
  -H "X-API-Key: bme_us_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v"
Query parameters:
ParameterRequiredDescription
periodNoEngagement window: 24hours (default), week, or month
timezoneNoIANA timezone code (default: UTC)
Response (200 OK): 
{
  "start": "2026-03-21T00:00:00.000Z",
  "end": "2026-03-28T00:00:00.000Z",
  "histogram": [
    {
      "date": "2026-03-21T00:00:00.000Z",
      "opens": 145,
      "clicks": 58
    },
    {
      "date": "2026-03-22T00:00:00.000Z",
      "opens": 32,
      "clicks": 12
    },
    {
      "date": "2026-03-23T00:00:00.000Z",
      "opens": 18,
      "clicks": 7
    },
    {
      "date": "2026-03-24T00:00:00.000Z",
      "opens": 8,
      "clicks": 3
    },
    {
      "date": "2026-03-25T00:00:00.000Z",
      "opens": 4,
      "clicks": 1
    },
    {
      "date": "2026-03-26T00:00:00.000Z",
      "opens": 2,
      "clicks": 0
    },
    {
      "date": "2026-03-27T00:00:00.000Z",
      "opens": 1,
      "clicks": 0
    }
  ]
}

​
Endpoint Summary

EndpointMethodDescription
/api/reports/dashboardGETDashboard snapshot (campaigns + contacts)
/api/reports/email/overallGETAggregate email performance
/api/reports/email/overall/histogramGETEmail performance time series
/api/reports/email/:idGETIndividual campaign report
/api/reports/email/:id/engagementGETCampaign engagement time series
All reports endpoints require reports:read scope and accept pastDays and timezone query parameters (except per-campaign endpoints which use period).

​
Common Errors

StatusErrorCauseFix
401UnauthorizedErrorInvalid or inactive API keyVerify your key in Settings > API Keys
403ForbiddenErrorKey lacks reports:read scopeCreate or upgrade your key with reports:read
400ValidationErrorInvalid pastDays value (must be 1-90) or invalid periodCheck query parameters
404RecordNotFoundCampaign ID does not existVerify the campaign ID from GET /api/email/campaign
429TooManyRequestsErrorRate limit exceededWait for the Retry-After period. See Rate Limits

​
Next Steps