email-competitive

Get the notable campaigns across watched brands

Returns the campaigns worth a second look across every brand the workspace watches, surfaced for what they did rather than for when they were sent.

Each campaign carries the signal that surfaced it: an unusually big send for its brand, a campaign read unusually well for its brand, or heavy spam placement at one mailbox provider. Every signal compares a campaign against its own brand's history, never against your other brands, so several brands can carry the same signal in one period.

Up to 100 findings are returned. Selection takes turns across brands in watchlist order until the response is full, prioritizing spam placement, biggest sends, then read-rate standouts within a brand. Returned findings retain watchlist, signal, domain, and source order. Your own sending is never included.

An empty list is an ordinary answer, not a failure: a signal only fires on a campaign that stands out for its own brand, and a watchlist of steady senders produces nothing. Check panel_status to tell that apart from the panel being unreachable.

This is a separate request from the watchlist on purpose, so a slow or degraded panel read cannot delay the watchlist itself.

get/v1/email/competitive/watchlist/notable

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/email/competitive/watchlist/notable
  • 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 notable campaigns for the period.

panel_status'ok' | 'not_in_panel' | 'no_data' | 'unavailable' required

Whether panel figures are available for a row, and when they are not, why.

ok means the panel reported figures for the requested period. not_in_panel means the panel does not track the sending domain at all, which is common for smaller and newer senders. no_data means the panel tracks the domain but observed no mail from it in the period. unavailable means the figures could not be retrieved this time and the same request may well succeed on a retry.

truncatedboolean required

Whether Bird omitted eligible panel findings to keep this response to 100 rows. False does not promise that the panel observed every qualifying campaign in the period.

Example response

{
  "period": {
    "days": 30,
    "from": "2026-07-13T09:00:00Z",
    "to": "2026-08-12T09:00:00Z"
  },
  "panel_status": "ok",
  "data": [
    {
      "watchlist_brand_id": "cwb_01krdgeqcxet5s7t44vh8rt9mg",
      "brand_name": "Allbirds",
      "signal": "read_rate_standout",
      "claim": {
        "text": "Biggest send in 7 days"
      },
      "evidence": {
        "ratio_to_median": 29.61,
        "read_rate_observations": 66,
        "mailbox_provider_spam_rate": 0.79,
        "mailbox_provider_observations": 199
      },
      "mailbox_provider": "gmail",
      "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",
        "reach": 410000,
        "read_rate": 0.228,
        "has_creative": true,
        "discount_percent": 40,
        "inbox_rate": 0.879,
        "spam_rate": 0.121
      }
    }
  ]
}

Changes

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