---
title: Get daily engagement events
openapi: /openapi/mailfully.yaml GET /v1/analytics/engagement
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://mailfully.com/docs/llms.txt). Append `.md` to any page URL for its markdown version.

`GET https://api.mailfully.com/v1/analytics/engagement`

Return retained raw open and click event counts by UTC day, scoped to the credential's environment. Each kind has total, likely, unlikely, and unknown automation buckets. Repeated events count separately; these are not unique people or the recipient-capped rollup counters/rates. Unknown includes older events without metadata and remains when excluding likely automation (total minus likely). No bucket proves a human action or Inbox placement. Days without events are omitted. Bounds are inclusive real calendar dates. Omitted to defaults to today's UTC date; omitted from to 30 days before today, independently of to. Rejects future to, reversed windows, and more than 93 inclusive days before retention clamping. Retention uses an exact timestamp, so the first retained day may be partial; an entirely expired window returns an empty data array. Requires read:analytics. A failed or timed-out read is an error, not zero events.

## Authentication

- `apiKey` — http bearer

## Query parameters

- `from` (string) — Inclusive lower bound as a `YYYY-MM-DD` day. Defaults to 30 days ago and is always clamped up to the plan retention floor.
- `to` (string) — Inclusive upper bound as a `YYYY-MM-DD` day. Defaults to the current UTC day.

## Response 200

Sparse daily raw event counts.
  - response (object)
    - `data` (array, required)
      - `items` (object)
        - `day` (string, date, required) — UTC event day; the first retained day may be partial.
        - `opens` (object, required) — Raw event counts; total equals likely plus unlikely plus unknown.
          - `total` (integer, required)
          - `likely` (integer, required)
          - `unlikely` (integer, required)
          - `unknown` (integer, required) — Includes historical events without an automation signal.
        - `clicks` (object, required) — Raw event counts; total equals likely plus unlikely plus unknown.
          - `total` (integer, required)
          - `likely` (integer, required)
          - `unlikely` (integer, required)
          - `unknown` (integer, required) — Includes historical events without an automation signal.

## Response 401

Authentication failed.
  - response (object)
    - `error` (object, required)
      - `type` (string, required) — Machine-readable error code.
      - `message` (string, required) — Human-readable error message.
      - `param` (string) — The offending field; present only on validation errors.

## Response 403

The credential is valid but not permitted.
  - response (object)
    - `error` (object, required)
      - `type` (string, required) — Machine-readable error code.
      - `message` (string, required) — Human-readable error message.
      - `param` (string) — The offending field; present only on validation errors.

## Response 422

The request failed validation.
  - response (object)
    - `error` (object, required)
      - `type` (string, required) — Machine-readable error code.
      - `message` (string, required) — Human-readable error message.
      - `param` (string) — The offending field; present only on validation errors.

## Response 500

An unexpected error occurred.
  - response (object)
    - `error` (object, required)
      - `type` (string, required) — Machine-readable error code.
      - `message` (string, required) — Human-readable error message.
      - `param` (string) — The offending field; present only on validation errors.


---

📦 **OpenAPI specs:** Every OpenAPI specification referenced by this documentation is available as a single download — https://mailfully.com/docs/api-specs.zip