An accepted send can fail later during delivery. Keeping its response headers lets support investigate the original call alongside the message's subsequent events.
Where do I find the request ID?
Read the X-Request-Id response header on successful and failed calls. Bird also includes request_id inside the top-level error object on failures.
Save the header when your client receives the response. Include it in logs for successful sends, since an unexpected delivery result can arrive later.
What should I send to support?
Send the request ID for the affected attempt, its time, the operation and the unexpected result. Include the HTTP status and any error code and name.
A retry has its own request ID. If the first attempt failed and the second succeeded, include the first attempt's ID when asking about the failure.
For delivery questions, include the message ID too. One email batch request can queue up to 100 messages under one request ID.
What should my client log?
Log the response header, HTTP status, request time and operation for each attempt. For errors, also record code, name and request_id from the envelope.
These fields answer separate questions. The code identifies the documented failure. The name makes logs readable. The request ID lets support trace the attempt.
Keep the returned message ID alongside your application's record of a send. Avoid logging credentials or message bodies just to retain these identifiers.
How do I connect events to my own records?
Attach your application's identifier using the fields the send endpoint supports. For email sends, metadata and tags are echoed in webhook events.
For example, an order identifier can connect a delivery event to the order that triggered the email. Keep the request ID separately for investigating the API call.
Which identifier should I use?
Use the request ID for one API attempt and the message ID for delivery history.
| Identifier | Use it to |
|---|---|
X-Request-Id | Ask support about one API attempt. |
| Message ID | Follow one message through its delivery events. |
Idempotency-Key | Retry the same write without deliberately creating another operation. |
webhook-id | Deduplicate repeated deliveries of the same event. |
Your identifier in metadata or tags | Join supported events to your application's records. |
Keep an idempotency key stable across retries of one write. The request ID changes with each attempt. A webhook event keeps its identifier across delivery retries.
The errors guide shows where the request ID appears in error responses.
In short
Log the response header.
X-Request-Ididentifies the attempt, whether it succeeded or failed. Errors also includerequest_idin their envelope.Keep each retry separate.
A retry gets a new request ID, even when it uses the same idempotency key.
Include the message ID for delivery questions.
One API call can queue several messages, so its request ID alone may not identify the affected recipient.
Use application identifiers to join records.
On email sends, metadata and tags carry your identifiers into webhook events.