Mail API reference

Mail API · Messages

get/v1/workspaces/{workspace_id}/messages/timelineAuth

Day-bucketed inbound message volume for a workspace

Counts INBOUND mail only: messages received by the workspace's mailboxes, in dense day buckets in [since, until). `metric=sent` (default, a historical name) counts received messages, not outbound sends; `metric=bounced` counts MX-time rejections matched to this workspace by envelope-to. For outbound counts and rates use `GET /emails/metrics`.

Path parameters

workspace_id*string · uuid

Id of the workspace.

Query parameters

granularity*enum (1)

Bucket size. Only `day` is supported today; the param is here so future hour/week additions don’t break clients.

since*string · date-time

Inclusive start of the window (ISO-8601). Treated in UTC for bucket alignment.

until*string · date-time

Exclusive end of the window (ISO-8601).

metricenum (2)

Which counter to bucket. `sent` (default) reads from received messages; `bounced` reads from MX-time rejections matching this workspace's mailbox addresses.

Response · 200

granularity*object

Bucket size of the series.

metric*object

What the series counts.

points*array

Dense day-bucketed counts for the requested window. Days with zero messages still appear with `count: 0`.

Example

Request

GET https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/messages/timeline
Authorization: Bearer YOUR_TOKEN

Response

{
  "granularity": {},
  "metric": {},
  "points": [
    {
      "date": "2026-04-02",
      "count": 42
    }
  ]
}