Create a draft
A standalone draft, or with thread_id and reply_to_email_id a reply draft in that thread. One unsent reply draft per email: creating another answers 200 with the existing one. A reply draft copies no recipients; set to before sending. attachments are kept encrypted with the draft until it is sent, rejected, expired or deleted. Nothing is sent until POST /inboxes/{inbox_id}/drafts/{draft_id}/send, or until send_at (BillionSend extension) when it is given: the draft is then sent as the caller at that time, through every rule and limit, and must have a recipient. With send_at, a reply draft for an email that already has one answers 409 instead of the existing draft.
/inboxes/{inbox_id}/draftsAuthorizationToken Bearer · headerobligatorioA BillionSend API key (bs_…).
inbox_idstringobligatorioThe inbox ID or its email address, such as support@example.com
application/jsontostring | string[] | nullAn address or a list of them; "Name <address>" works too
Mostrar propiedadesOcultar propiedades
stringstringstringnullccstring | string[] | nullAn address or a list of them; "Name <address>" works too
Mostrar propiedadesOcultar propiedades
stringstringstringnullbccstring | string[] | nullAn address or a list of them; "Name <address>" works too
Mostrar propiedadesOcultar propiedades
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 propiedadesOcultar propiedades
objectfilenamestring | boolean | nullMostrar propiedadesOcultar propiedades
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)
thread_idstring<uuid>With reply_to_email_id: a reply draft in this thread
reply_to_email_idstring<uuid>The email of the thread the draft answers
The existing reply draft
objectstringobligatorioinbox_draftidstring<uuid>obligatoriotypestringobligatoriostandalonereplytostring[] | nullobligatorioccstring[]obligatoriobccstring[]obligatoriosubjectstring | nullobligatoriohtmlstring | nullobligatoriotextstring | nullobligatoriothread_idstring<uuid> | nullobligatorioreply_to_email_idstring<uuid> | nullobligatorioemail_idstring<uuid> | nullobligatoriocreated_atstringobligatorioupdated_atstringobligatorioattachmentsobject[]obligatorioThe draft's files, by position; empty once it is sent, rejected or expired
Mostrar propiedadesOcultar propiedades
objectidstringobligatoriofilenamestringobligatoriocontent_typestringobligatoriosizeintegerobligatoriostatusstringobligatoriodraftpending_approvalsentrejectedexpiredapproval_reasonsstring[]obligatorioforwardbooleanobligatoriodecided_bystring | nullobligatoriodecided_atstring | nullobligatorioexpires_atstring | nullobligatoriosend_atstring | nullobligatorioBillionSend extension: when the scheduled send goes out; null when not scheduled
send_errorstring | nullobligatorioBillionSend 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
Created
objectstringobligatorioinbox_draftidstring<uuid>obligatoriotypestringobligatoriostandalonereplytostring[] | nullobligatorioccstring[]obligatoriobccstring[]obligatoriosubjectstring | nullobligatoriohtmlstring | nullobligatoriotextstring | nullobligatoriothread_idstring<uuid> | nullobligatorioreply_to_email_idstring<uuid> | nullobligatorioemail_idstring<uuid> | nullobligatoriocreated_atstringobligatorioupdated_atstringobligatorioattachmentsobject[]obligatorioThe draft's files, by position; empty once it is sent, rejected or expired
Mostrar propiedadesOcultar propiedades
objectidstringobligatoriofilenamestringobligatoriocontent_typestringobligatoriosizeintegerobligatoriostatusstringobligatoriodraftpending_approvalsentrejectedexpiredapproval_reasonsstring[]obligatorioforwardbooleanobligatoriodecided_bystring | nullobligatoriodecided_atstring | nullobligatorioexpires_atstring | nullobligatoriosend_atstring | nullobligatorioBillionSend extension: when the scheduled send goes out; null when not scheduled
send_errorstring | nullobligatorioBillionSend 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
statusCodenumberobligatorionamestringobligatoriomessagestringobligatorioRestricted API key, the inbox's or the shared domain's rules, or held mail
statusCodenumberobligatorionamestringobligatoriomessagestringobligatorioNot found
statusCodenumberobligatorionamestringobligatoriomessagestringobligatorioIdempotency conflict, or a draft already sent
statusCodenumberobligatorionamestringobligatoriomessagestringobligatorioValidation error
statusCodenumberobligatorionamestringobligatoriomessagestringobligatorioThe 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)
statusCodenumberobligatorionamestringobligatoriomessagestringobligatorio