email-broadcasts

Get the email send allowance for a broadcast

Returns how many recipients the organization's email send allowance covers. Use this estimate before sending or scheduling to check whether the daily or monthly email limit would restrict the send.

recipients is the number of contacts the broadcast could reach now. It matches the sendable count from the audience counts. allowed is the number covered by the email send allowance. It equals recipients when no email limit restricts the send. limited_by identifies the monthly email limit for the billing period or the daily email limit that prevents the rest from receiving the broadcast. limit and remaining describe that email limit. resets_at is its reset time. For a monthly email limit, limit_reason explains what sets it if you can read the organization's billing.

Pass send_at to check a later send, such as the scheduled_at you plan to use. If a daily or monthly window resets by that time, the check uses its full allowance. Otherwise, it uses the allowance remaining now. The check estimates your send quota using current limits without subtracting broadcasts that are scheduled but have not sent yet, so broadcasts scheduled for the same period may together exceed the limit even if each check shows enough quota. Without send_at, it checks a send now.

broadcasts reports the separate broadcast count allowance for the billing period, or the UTC day when no current billing period is available. Sending or scheduling a draft uses one broadcast from this allowance. send_at does not change broadcasts.

These counts are live estimates. Audience membership, suppressions, and email usage can change before the broadcast sends. This check reserves nothing. The email send allowance is checked again when the broadcast sends. The broadcast must have an audience selected. A broadcast without an audience returns a 422.

get/v1/email/broadcasts/{broadcast_id}/send-quota

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/email/broadcasts/{broadcast_id}/send-quota
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Path parameters

broadcast_idstring required
Example:eb_01krdgeqcxet5s7t44vh8rt9mg

ID of the broadcast to check the email send allowance for.

Query parameters

send_atstring date-time
Example:2026-11-02T09:00:00Z

The proposed send time as an RFC 3339 date-time. If a daily or monthly window resets at or before this time, the check uses its full allowance. Otherwise, it uses the allowance remaining now. The check estimates your send quota at this time using current limits without subtracting broadcasts that are scheduled but have not sent yet, including those scheduled before this time. It does not reflect plan changes or temporary limit changes that take effect before this time.

Must be at least 30 seconds and no more than 365 days in the future, the same range accepted by scheduled_at. Omit send_at to check a send now. A scheduled broadcast's scheduled_at is used only if you pass it as send_at.

Does not change broadcasts. The broadcast count allowance is used when you submit the send or schedule request.

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 recipients covered by the broadcast's email send allowance.

recipientsinteger required

Number of contacts the broadcast could reach now. Excludes contacts without an email address and contacts suppressed for the broadcast's category. Matches the sendable count from the broadcast's audience counts.

allowedinteger required

Number of recipients covered by the organization's email send allowance at send_at, or now if you omit it. Equals recipients when no email limit restricts the send. It is lower when the remaining allowance cannot cover the audience.

Partially covered broadcasts send in whole batches. This count is rounded down to a batch boundary and can be lower than remaining. Read this value directly instead of calculating it from limit and remaining.

A value of 0 means no recipients would receive the broadcast. This happens if the audience exceeds the full email limit, which rejects the send, or if the remaining allowance cannot cover a batch.

limited_by'none' | 'monthly' | 'daily' required

The email limit that prevents a broadcast from reaching its full audience.

  • none: the email send allowance covers every recipient.
  • monthly: the monthly email limit for the billing period.
  • daily: the daily email limit, which resets at the end of each UTC day.

When both email limits apply, the response reports the more restrictive one. If you pass send_at, the check evaluates both at that time.

limitinteger

The email limit identified by limited_by, in emails. Omitted when no email limit restricts the send.

remaininginteger

The allowance remaining under the email limit identified by limited_by, in emails, at send_at, or now if you omit it. If the window resets by send_at, the check uses its full allowance. Omitted when no email limit restricts the send.

resets_atstring date-time

When usage resets to 0 for the email limit identified by limited_by, evaluated at send_at, or now if you omit it.

A broadcast sent before this time uses the same window and the allowance left after other sends. A broadcast sent at or after this time uses a new window. If recipients exceeds the full limit, the send is rejected in any window with that limit. Pass the later time as send_at to check whether the other email limit still restricts the send.

Omitted when no email limit restricts the send, when the reset is at or before send_at, or when the billing period has ended and the next one has not started.

limit_reason'plan' | 'overage_off' | 'overdue_payment' | 'unfunded' | 'overage_ceiling' | 'custom_limit'

What sets the monthly email limit and how to raise it.

  • plan: the organization's monthly email limit. This is the plan's included volume unless we have set a different limit for the organization. If the limit matches the included volume, a plan with more included volume raises it. Otherwise, contact Bird support.
  • overage_off: email overage is turned off, so sending stops at the included volume. Turn email overage back on to raise the monthly email limit.
  • overdue_payment: an overdue payment pauses email overage, so sending stops at the included volume. Pay the overdue invoice to raise the monthly email limit.
  • unfunded: the wallet cannot cover email overage, or its funding cannot be confirmed, so sending stops at the included volume. Top up the wallet if it lacks funds. Email overage resumes once sufficient funding is confirmed.
  • overage_ceiling: email overage is billed up to a configured multiple of the included volume. A plan with more included volume raises the email overage ceiling.
  • custom_limit: we have set a monthly email limit for the organization that differs from the plan's included volume. Contact Bird support to change it. These limits currently report as plan. This enum value is declared in advance so reporting them as custom_limit will not be a breaking change.

Example response

{
  "recipients": 12000,
  "allowed": 5000,
  "limit": 50000,
  "remaining": 7000,
  "resets_at": "2026-09-01T00:00:00Z",
  "broadcasts": {
    "limit": 20,
    "remaining": 4,
    "resets_at": "2026-09-01T00:00:00Z"
  }
}

Changes

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