API documentation (sending email) — Bird Email API (formerly SparkPost)

Cited by

Facts read from this source

• Send endpoint Report an error

  “POST /v1/email/messages sends one email. Provide a sender, recipients, and content in a JSON payload. The API returns 202 Accepted with a message ID, then delivers the email asynchronously.”

• Regional hosts Report an error

  “Use your regional host (https://us1.platform.bird.com or https://eu1.platform.bird.com) with a matching bk_{region}_... key.”

• Recipient limits Report an error

  “to, cc, and bcc each take up to 50 addresses, and to needs at least one.”

• Reply to limit Report an error

  “reply_to takes 1 to 25 addresses, in the same formats as recipients.”

• Subject limit Report an error

  “subject is required for inline sends, up to 998 characters.”

• Body limit Report an error

  “Provide html, text, or both, each up to 524,288 characters.”

• Headers limit Report an error

  “headers is a string-to-string object for your own headers, for example {"X-Campaign": "spring-2026"}, capped at 25 headers with values up to 998 characters.”

• Tags limits Report an error

  “tags are structured {name, value} pairs: up to 20 per send, name up to 32 characters, value up to 64, ASCII letters, digits, underscore, and hyphen only, and names unique within the send.”

• Metadata limit Report an error

  “metadata is an arbitrary JSON object, up to 2 KB serialized.”

• Parameters limit Report an error

  “put {{ variable }} tokens in the subject or body and pass their values in parameters, up to 16 KB serialized.”

• Tracking defaults Report an error

  “track_opens and track_clicks both default to true.”

• Category values Report an error

  “category classifies the content and sets suppression policy: marketing blocks delivery on every suppression reason and on any opt-out, and transactional delivers through a complaint suppression or a marketing-only opt-out”

• Ip pool Report an error

  “ip_pool_id picks the sending pool: a pool ID (ipp_...), or ipp_shared to route through the shared pool explicitly. Omit it for your organization's default pool.”

• Template liquid Report an error

  “A template's content is Liquid, so besides plain {{ variable }} substitution it can use filters, {% if %} conditionals, and {% for %} loops.”

• Attachments limit Report an error

  “attachments takes up to 20 files per message, as base64-encoded bytes inline. We reject a send whose estimated generated message size passes 20 MB, measured after base64 encoding, so keep raw attachment content at or below 15 MB for headroom.”

• Scheduled sending Report an error

  “scheduled_at RFC 3339 timestamp no Schedule inline content or a template; see scheduled sending”

• Batch endpoint Report an error

  “POST /v1/email/batches accepts up to 100 independent messages and validates them as one unit.”

• Idempotency Report an error

  “Send an Idempotency-Key header with a unique value per logical send. If a request succeeded but you never saw the response, replay it with the same key. The API returns the original result instead of sending a second email and includes an Idempotency-Replay header.”

• Suppressed recipients accepted Report an error

  “Recipients on the workspace suppression list do not fail the request. It still returns a 202, and each suppressed recipient comes back on the read endpoints as status: rejected with the reason recipient_suppressed”

• Placeholder domains rejected Report an error

  “The API rejects placeholder domains with a 422: example.com, example.net, example.org, example.edu, test.com, and anything under the reserved .test, .example, .invalid, or .localhost TLDs.”

• Per recipient metering Report an error

  “Email sends meter per recipient, so a message to three recipients counts as three sends.”

• Free plan allowance Report an error

  “On the Email Free plan, sends count against its monthly and daily allowance.”

• Paid plan billing Report an error

  “On a paid Email plan, each send is charged from your wallet at the plan's rate per 1,000 emails.”

• Liquid escaping Report an error

  “Values inserted into HTML are escaped so they cannot change the surrounding markup. For a complete link or image URL, use {{ link }} without url_encode.”

• Marketing unsubscribe default Report an error

  “Transactional sends accept List-Unsubscribe and List-Unsubscribe-Post. Marketing sends use Bird-managed unsubscribe by default.”

• Webhook echo Report an error

  “Every webhook event includes the tags and metadata together with the correlation IDs (email_id, recipient_id), so you can reconcile against your own records without a second lookup.”

• Language support Report an error

  “language picks one of the template's languages. Omit it to send the template's default.”

• Template deletion behavior Report an error

  “We pin the published version, selected language and parameter values at acceptance. If you delete the template before the send time, the message is rejected with generation_failure.”

• Unknown template errors Report an error

  “An unknown template is rejected with a 404, and a template with no published version with a 422.”

• Reserved parameter name Report an error

  “Each parameter name is a single word, such as first_name; dotted names and the reserved name bird are rejected.”

2 facts read from this page are not shown because they could not be confirmed on the page as captured.

Scores citing this record

• The Agency Lead Sending API, SMTP & developer experience
• The Agency Lead Pricing transparency
• The Data Protection Officer Sending API, SMTP & developer experience
• The Data Protection Officer European sovereignty
• The Shop Operator Sending API, SMTP & developer experience
• The Platform Engineer Sending API, SMTP & developer experience
• The Platform Engineer European sovereignty
• The Platform Engineer Pricing transparency
• The SaaS Developer Sending API, SMTP & developer experience
• The SaaS Developer Message data, retention & security
• The SaaS Developer Pricing transparency
• The Skeptic Sending API, SMTP & developer experience
• The Skeptic Pricing transparency