Sign inGet Started
Commencer
Guides
Référence API
SDK
CLI
Base de connaissances
Changelog

Get the email send allowance for a broadcast

GET
/v1/email/broadcasts/{broadcast_id}/send-quota
const quota = await bird.broadcasts.sendQuota("eb_01krdgeqcxet5s7t44vh8rt9mg");
if (quota.allowed < quota.recipients) {
  console.log(`${quota.limited_by} allowance covers only ${quota.allowed}`);
}
Réponse200
{
  "recipients": 12000,
  "allowed": 5000,
  "limited_by": "monthly",
  "limit": 50000,
  "remaining": 7000,
  "resets_at": "2026-09-01T00:00:00Z",
  "limit_reason": "plan",
  "broadcasts": {
    "limit": 20,
    "remaining": 4,
    "resets_at": "2026-09-01T00:00:00Z"
  }
}

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.

Paramètres

broadcast_idstring

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

Paramètres de requête

send_atstring

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.

Contenu de la réponse

recipients
integer
obligatoire

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.

allowed
integer
obligatoire

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
string
obligatoire

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.

Possible values: none, monthly, daily

limit
integer

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

remaining
integer

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_at
string

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
string

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.

Possible values: plan, overage_off, overdue_payment, unfunded, overage_ceiling, custom_limit

broadcasts
object

The organization's broadcast count allowance for the current window. This counts broadcasts rather than emails. The window is the billing period, or the UTC day when no current billing period is available.

Sending or scheduling a draft uses one broadcast from the window current when you submit the request. The scheduled send time does not determine the window. Sending an already scheduled broadcast again uses no additional broadcast allowance. send_at on the send-quota request does not change this allowance.

Afficher les attributs enfants

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet.

Essayez la pratique et obtenez un guide d'implémentation