email-competitive

Get the competitor watchlist with its latest figures

Returns every competitor brand on the workspace's watchlist, plus a row for your own sending, each with estimated send volume and how it changed against the previous period, how often the brand sends, inbox placement, estimated read rate, audience overlap with you, and the most recent campaign seen.

Figures about a competitor are estimates from an email panel, which observes a sample of real inboxes and scales what it sees up to a whole audience. They are fetched while the request runs; the panel can revise recent measurements, so two requests minutes apart can differ. Your send volume and cadence cover the workspace, while your panel rates and overlap use its highest-volume sending domain. The provenance object records each metric's source.

Interpret null using each field's description: rates can be unavailable, while a last campaign can be unobserved and overlap can be absent from the panel response. A 0 means a measurement. panel_status distinguishes an untracked domain, no observed mail and a temporarily unavailable panel.

esp and list_size are the exception, and are always null here. Read a single brand to get them.

get/v1/email/competitive/watchlist

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/email/competitive/watchlist
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Query parameters

range7 | 30 | 90
Example:30

How many days back the response covers, counting from now. One of three fixed trend windows rather than an open date range, matching how a competitive-intelligence chart is read. Defaults to 30.

Headers

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

The watchlist with its figures for the requested period.

Example response

{
  "period": {
    "days": 30,
    "from": "2026-07-13T09:00:00Z",
    "to": "2026-08-12T09:00:00Z"
  },
  "summary": {
    "share_of_volume_percent": 10.5,
    "share_of_volume_change_points": -1.2,
    "competitor_sends": 4240000,
    "competitor_sends_change_percent": 12,
    "peer_cadence_median_per_week": 4.4,
    "peer_inbox_placement_median_rate": 0.892
  },
  "data": [
    {
      "watchlist_brand_id": "cwb_01krdgeqcxet5s7t44vh8rt9mg",
      "name": "Everlane",
      "industry": "DTC Apparel",
      "sending_domains": [
        "everlane.com"
      ],
      "esp": "Klaviyo",
      "list_size": 1240000,
      "panel_status": "ok",
      "sends": 1240000,
      "sends_change_percent": 18,
      "cadence_per_week": 5.2,
      "inbox_placement_rate": 0.889,
      "read_rate": 0.192,
      "audience_overlap_rate": 0.24,
      "last_campaign": {
        "id": "3914827265",
        "subject": "The Summer Sale: 40% off everything",
        "sent_at": "2026-08-09T14:02:00Z",
        "image_url": "https://images.example.com/creatives/c154c8c4-6356-40e6-92d2-7c6727ec36ca.jpg"
      },
      "provenance": {
        "sends": "panel",
        "cadence_per_week": "panel",
        "inbox_placement_rate": "panel",
        "read_rate": "panel",
        "audience_overlap_rate": "panel",
        "last_campaign": "panel"
      }
    }
  ]
}

Changes

No recorded changes to this operation across all 2 revisions of this API.