View Reports

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 "https://api-us-west-2-c1.benchmarkemail.com/api/reports/dashboard?pastDays=30&timezone=America/New_York" \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Query parameters:

Parameter	Required	Description
`pastDays`	Yes	Number of days to look back (1-90)
`timezone`	No	IANA 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 "https://api-us-west-2-c1.benchmarkemail.com/api/reports/email/overall?pastDays=30&timezone=America/New_York" \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

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 "https://api-us-west-2-c1.benchmarkemail.com/api/reports/email/overall/histogram?pastDays=30&timezone=America/New_York" \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

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 https://api-us-west-2-c1.benchmarkemail.com/api/reports/email/66f1a6e4698f1bca60426002 \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

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 "https://api-us-west-2-c1.benchmarkemail.com/api/reports/email/66f1a6e4698f1bca60426002/engagement?period=week&timezone=America/New_York" \
  -H "X-API-Key: bme_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Query parameters:

Parameter	Required	Description
`period`	No	Engagement window: `24hours` (default), `week`, or `month`
`timezone`	No	IANA 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

Endpoint	Method	Description
`/api/reports/dashboard`	GET	Dashboard snapshot (campaigns + contacts)
`/api/reports/email/overall`	GET	Aggregate email performance
`/api/reports/email/overall/histogram`	GET	Email performance time series
`/api/reports/email/:id`	GET	Individual campaign report
`/api/reports/email/:id/engagement`	GET	Campaign 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

Status	Error	Cause	Fix
`401`	`UnauthorizedError`	Invalid or inactive API key	Verify your key in Settings > API Keys
`403`	`ForbiddenError`	Key lacks `reports:read` scope	Create or upgrade your key with `reports:read`
`400`	`ValidationError`	Invalid `pastDays` value (must be 1-90) or invalid `period`	Check query parameters
`404`	`RecordNotFound`	Campaign ID does not exist	Verify the campaign ID from `GET /api/email/campaign`
`429`	`TooManyRequestsError`	Rate limit exceeded	Wait for the `Retry-After` period. See Rate Limits

Next Steps

Manage Campaigns — create and manage the campaigns you are reporting on
Search Contacts — find contacts for targeted campaign analysis
Manage Lists — manage the lists your campaigns send to

Get Started

Scenarios

View reports

View Reports

Goal

Prerequisites

Steps

1. Get dashboard summary

2. Get email performance overview

3. Get email performance histogram

4. Get campaign-specific report

5. Get campaign engagement details

Endpoint Summary

Common Errors

Next Steps

Get Started

Scenarios

​View Reports

​Goal

​Prerequisites

​Steps

​1. Get dashboard summary

​2. Get email performance overview

​3. Get email performance histogram

​4. Get campaign-specific report

​5. Get campaign engagement details

​Endpoint Summary

​Common Errors

​Next Steps

View Reports

Goal

Prerequisites

Steps

1. Get dashboard summary

2. Get email performance overview

3. Get email performance histogram

4. Get campaign-specific report

5. Get campaign engagement details

Endpoint Summary

Common Errors

Next Steps