> ## Documentation Index
> Fetch the complete documentation index at: https://developers.benchmarkemail.io/llms.txt
> Use this file to discover all available pages before exploring further.

# View Reports

> Retrieve dashboard summaries, email performance metrics, and engagement data.

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.

```bash theme={null}
curl "<your-api-base-url>/api/reports/dashboard?pastDays=30&timezone=America/New_York" \
  -H "X-API-Key: bme_us_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v"
```

**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`):

```json theme={null}
{
  "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.

```bash theme={null}
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`):

```json theme={null}
{
  "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.

```bash theme={null}
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`):

```json theme={null}
{
  "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`).

```bash theme={null}
curl "<your-api-base-url>/api/reports/email/66f1a6e4698f1bca60426002" \
  -H "X-API-Key: bme_us_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v"
```

**Response** (`200 OK`):

```json theme={null}
{
  "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.

```bash theme={null}
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:**

| Parameter | Required | Description |
| - | - | - |
| `period` | No | Engagement window: `24hours` (default), `week`, or `month` |
| `timezone` | No | IANA timezone code (default: `UTC`) |

**Response** (`200 OK`):

```json theme={null}
{
  "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](/rate-limits) |

## Next Steps

* [Manage Campaigns](/scenarios/manage-campaigns) — create and manage the campaigns you are reporting on
* [Search Contacts](/scenarios/search-contacts) — find contacts for targeted campaign analysis
* [Manage Lists](/scenarios/manage-lists) — manage the lists your campaigns send to


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.