Buzzz API Reference

This endpoint defaults to transactional: one-to-one mail the recipient is expecting — receipts, password resets, alerts. Transactional mail carries no unsubscribe headers or footer, and is still delivered to addresses that unsubscribed from your marketing lists (though never to addresses that bounced or filed a spam complaint).

Promotional mail must be sent with "category": "marketing". Marketing sends automatically get RFC 8058 List-Unsubscribe and List-Unsubscribe-Post headers plus an unsubscribe footer, and are rejected for recipients who have unsubscribed. The unsubscribe link identifies the to address, so send marketing mail to one recipient per request.

Sending promotional content as transactional is a Terms of Service violation: it puts the shared sending reputation at risk and denies recipients the opt-out the law requires.

With scheduled_at the request returns 202 and a record in status SCHEDULED instead of sending immediately. The allowance is committed when the send is accepted, not when it fires, and entitlements are re-checked at fire time — a plan that shrank in the meantime refuses the send rather than exceeding it.

DELETE /api/v1/emails/{id} cancels it. Before the worker picks the email up you get 200 and the record moves to CANCELLED, which is not counted against your allowance. Once it has been picked up you get 409: it may already be with the provider, so no promise can be made about stopping it.

Send an Idempotency-Key header (up to 255 characters of A-Z a-z 0-9 _ - : . — a UUID or ULID does nicely) to make a retry safe. Within 24 hours a repeat of the same key returns the first response verbatim — same id, same status — and sends nothing further.

A key whose first request is still in flight returns 409 idempotency_key_in_use; retry in a moment for the stored result. Keys pin only successful requests: one that was refused or failed releases its key, so a corrected retry is a fresh request.

Each attachment carries a filename and either content (base64) or url — a URL of a file already uploaded to your account. Arbitrary URLs are not fetched. Together they may total 10 MB once decoded; a bigger request is rejected with 400 attachments_too_large.

Attachments are transactional only: a marketing send is rejected, and so is a send with scheduled_at — the bytes are not stored, so there would be nothing left to attach when the schedule fires. An account configured to send through Gmail gets 400 attachments_unsupported; every other provider carries them.

The response is always 200 with data holding one entry per message, in request order: either { id, status, message } or { error, message, statusCode }. A malformed message, or one whose recipient is suppressed, fails on its own without touching its siblings.

Your monthly allowance is checked once, for the batch as a whole: if the whole batch does not fit, the request is refused with 402 and nothing is sent. Authentication and plan-level refusals are likewise whole-request.

Unlike the email endpoint, this one defaults to marketing: the stricter setting. A marketing SMS is never delivered to a number that replied STOP, nor to one the carrier has blocked. If you never send the field, nothing about your integration changes.

Send one-time passcodes, alerts and other messages the recipient is expecting with "category": "transactional". Transactional narrows which opt-outs apply — it does not turn opt-out enforcement off. A voluntary STOP no longer blocks the send, because withdrawing consent to promotions is not a request to be locked out of your own account. A carrier-level block still refuses it: the carrier will not deliver the message whatever you label it.

Transactional sends require the transactional_sms entitlement on your account. Without it the request is refused rather than quietly downgraded, so a misconfigured integration fails loudly instead of dropping passcodes. Labelling promotional content as transactional is a Terms of Service violation and, for SMS to numbers that opted out, a legal exposure under the TCPA.

With scheduled_at the request returns 202 and a record in status SCHEDULED instead of sending immediately. The allowance is committed when the send is accepted, not when it fires, and entitlements are re-checked at fire time — a plan that shrank in the meantime refuses the send rather than exceeding it.

DELETE /api/v1/sms/{id} cancels it. Before the worker picks the message up you get 200 and the record moves to CANCELLED, which is not counted against your allowance. Once it has been picked up you get 409: it may already be with the provider, so no promise can be made about stopping it.

Send an Idempotency-Key header (up to 255 characters of A-Z a-z 0-9 _ - : . — a UUID or ULID does nicely) to make a retry safe. Within 24 hours a repeat of the same key returns the first response verbatim — same id, same status — and sends nothing further.

A key whose first request is still in flight returns 409 idempotency_key_in_use; retry in a moment for the stored result. Keys pin only successful requests: one that was refused or failed releases its key, so a corrected retry is a fresh request.