Send an email from an inbox
Sends a new conversation from the inbox address in one call (to, subject, html and/or text, optional cc, bcc and attachments as POST /emails takes them). It runs the same rules as a reply: an inbox that may not start conversations, a first-time recipient past the ramp, or requires_approval: true keeps it as a draft for a person to approve and the answer is 202 with the Draft. Accepts an Idempotency-Key. An inbox on the shared domain takes no attachments.
/inboxes/{inbox_id}/emailsAuthorizationToken Bearer · headerobligatorioA BillionSend API key (bs_…).
inbox_idstringobligatorioThe inbox ID or its email address, such as support@example.com
Idempotency-Keystring1 to 256 characters. A retry with the same key and the same body answers the original response instead of sending again; the same key with a different body answers 409 invalid_idempotent_request.
application/jsontostring | string[]obligatorioAn address or a list of them; "Name <address>" works too
Mostrar propiedadesOcultar propiedades
stringstringstringccstring | string[]An address or a list of them; "Name <address>" works too
Mostrar propiedadesOcultar propiedades
stringstringstringbccstring | string[]An address or a list of them; "Name <address>" works too
Mostrar propiedadesOcultar propiedades
stringstringstringsubjectstringobligatorio1-2000 characters on one line
htmlstringHTML body
textstringPlain-text body
attachmentsobject[] | 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>">
pathstringheadersanyNot supported: only an empty value is accepted, anything else answers 422
requires_approvalbooleanBillionSend extension: hold the email as a draft that a person approves (202 with the Draft)
Sent
idstring<uuid>obligatorioThe ID of the sent email: GET /emails/{id} reads it
thread_idstring<uuid> | nullobligatorioBillionSend extension: the thread the email was sent in
Held for approval
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