Update a draft
Each given field replaces the stored one; null clears it. Setting html or text replaces the whole body: the part left out becomes null. attachments replaces the whole list (null or an empty list removes the files). A sent draft, or one that changed during the request, answers 409. An edit by an agent sends a draft waiting for approval back to draft. send_at (BillionSend extension) schedules the draft to be sent as the caller, or reschedules it, and clears send_error; null cancels the schedule. A draft waiting for approval cannot be scheduled (409). When the scheduled send goes out, the draft becomes sent; when the inbox’s rules hold it, pending_approval; when it is refused (the key revoked, the inbox deleted, a limit reached), it stays a draft with send_at null, send_error set and an inbox.draft.send_failed webhook.
/inboxes/{inbox_id}/drafts/{draft_id}AuthorizationToken Bearer · headerobrigatórioA BillionSend API key (bs_…).
inbox_idstringobrigatórioThe inbox ID or its email address, such as support@example.com
draft_idstring<uuid>obrigatórioapplication/jsontostring | string[] | nullAn address or a list of them; "Name <address>" works too
Mostrar propriedadesOcultar propriedades
stringstringstringnullccstring | string[] | nullAn address or a list of them; "Name <address>" works too
Mostrar propriedadesOcultar propriedades
stringstringstringnullbccstring | string[] | nullAn address or a list of them; "Name <address>" works too
Mostrar propriedadesOcultar propriedades
stringstringstringnullsubjectstring | nullhtmlstring | nulltextstring | nullattachmentsobject[] | nullFiles with base64 content (no remote paths), 10 MiB decoded in all; none on the shared domain. A held send keeps them with its draft
Mostrar propriedadesOcultar propriedades
objectfilenamestring | boolean | nullMostrar propriedadesOcultar propriedades
stringbooleannullcontentstringcontent_typestringcontent_idstringInline part: the HTML shows it with <img src="cid:<content_id>">
pathstringsend_atstring | nullBillionSend extension: send the draft at this time, as the caller, within 30 days: an ISO 8601 datetime with offset (e.g. "2026-09-01T12:00:00Z") or a relative time like "in 2 hours". A past time sends it within a minute; null cancels. The send runs every rule and limit then; a refused one leaves the draft unsent with send_error set and fires inbox.draft.send_failed. A draft waiting for approval cannot be scheduled (409)
Draft
objectstringobrigatórioinbox_draftidstring<uuid>obrigatóriotypestringobrigatóriostandalonereplytostring[] | nullobrigatórioccstring[]obrigatóriobccstring[]obrigatóriosubjectstring | nullobrigatóriohtmlstring | nullobrigatóriotextstring | nullobrigatóriothread_idstring<uuid> | nullobrigatórioreply_to_email_idstring<uuid> | nullobrigatórioemail_idstring<uuid> | nullobrigatóriocreated_atstringobrigatórioupdated_atstringobrigatórioattachmentsobject[]obrigatórioThe draft's files, by position; empty once it is sent, rejected or expired
Mostrar propriedadesOcultar propriedades
objectidstringobrigatóriofilenamestringobrigatóriocontent_typestringobrigatóriosizeintegerobrigatóriostatusstringobrigatóriodraftpending_approvalsentrejectedexpiredapproval_reasonsstring[]obrigatórioforwardbooleanobrigatóriodecided_bystring | nullobrigatóriodecided_atstring | nullobrigatórioexpires_atstring | nullobrigatóriosend_atstring | nullobrigatórioBillionSend extension: when the scheduled send goes out; null when not scheduled
send_errorstring | nullobrigatórioBillionSend extension: the error name of the last scheduled send that was refused (e.g. invalid_api_key, inbox_send_cap_reached, not_found); null otherwise
Missing, malformed, unknown or revoked API key
statusCodenumberobrigatórionamestringobrigatóriomessagestringobrigatórioRestricted API key, the inbox's or the shared domain's rules, or held mail
statusCodenumberobrigatórionamestringobrigatóriomessagestringobrigatórioNot found
statusCodenumberobrigatórionamestringobrigatóriomessagestringobrigatórioIdempotency conflict, or a draft already sent
statusCodenumberobrigatórionamestringobrigatóriomessagestringobrigatórioValidation error
statusCodenumberobrigatórionamestringobrigatóriomessagestringobrigatórioThe inbox's daily send limit, or the team's daily limit for mail from the shared domain, or the rate limit (rate_limit_exceeded, with Retry-After)
statusCodenumberobrigatórionamestringobrigatóriomessagestringobrigatório