GuidesAPI Reference
Send API

Send bulk messages

Queue one templated email message for multiple recipients.

Prerequisite

This endpoint requires an existing Delivery account, a configured sending domain, and a Send API bearer token created for that Delivery account.

Bulk messages use Handlebars-style template variables, written as {{variable_name}}, inside the base message fields such as subject, text_body, html_body, headers, metadata, tags, and attachment filenames or content IDs. For each item in recipients, the API renders a dedicated message using that recipient's substitutions object. The special {{email}} variable is always available and contains the recipient email address. By default, every recipient must provide all variables used by the template; set options.strict_substitutions to false if missing variables should render as empty values instead.

POST/v1/send/bulk

Authorization

ApiBearerAuth
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

message*BulkMessageBulkMessage

Base message template for /v1/send/bulk. The to field is not allowed; the recipient is populated from each recipients[].email value. At least one body among text_body or html_body is required. Handlebars placeholders are supported in message fields. Address fields are rendered per recipient and normalized by the worker before final delivery. Unknown message properties are accepted and ignored.

Fields: BulkMessage
from*AddressAddress

Single email address. Accepts an RFC 5322 mailbox string such as Sender Name <sender@example.com> or an object with address and optional name.

Fields: Address
address*string

Email address.

name?string
cc?Address[]AddressList

Recipient list. Accepts one RFC 5322 mailbox string, a comma-separated RFC 5322 string, one address object, or an array of address strings/objects.

Array item: Address
address*string

Email address.

name?string
bcc?Address[]AddressList

Recipient list. Accepts one RFC 5322 mailbox string, a comma-separated RFC 5322 string, one address object, or an array of address strings/objects.

Array item: Address
address*string

Email address.

name?string
reply_to?Address[]AddressList

Recipient list. Accepts one RFC 5322 mailbox string, a comma-separated RFC 5322 string, one address object, or an array of address strings/objects.

Array item: Address
address*string

Email address.

name?string
subject*string
text_body?string

Required when html_body is absent.

html_body?string

Required when text_body is absent.

headers?object

Custom headers. Values can be string, number, boolean, or arrays of those primitive values.

attachments?Attachment[]
Array item: Attachment
filename*string
content_type*string
content*string

Base64 encoded content.

Format byte
disposition?string

Defaults to inline when content_id is provided; otherwise defaults to attachment.

Default attachmentValues attachment | inline
content_id?string

Required for inline attachments; if provided, disposition must be inline. Used as CID.

tags?string[]
metadata?object
recipients*BulkRecipient[]
Array item: BulkRecipient
email*AddressAddress

Single email address. Accepts an RFC 5322 mailbox string such as Sender Name <sender@example.com> or an object with address and optional name.

Fields: Address
address*string

Email address.

name?string
substitutions?object
metadata?object
options?BulkSendOptionsBulkSendOptions

Controls how bulk message templates are rendered for each recipient. Unknown options are accepted and ignored.

Fields: BulkSendOptions
strict_substitutions?boolean

When true, every recipient must provide all variables used by the message template. When false, missing variables render as empty values.

Default true

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://delivery.qboxmail.com/v1/send/bulk" \  -H "Authorization: Bearer <SEND_API_TOKEN>" \  -H "Content-Type: application/json" \  -d '{    "message": {      "from": "sender@example.com",      "subject": "Welcome {{first_name}}",      "html_body": "<p>Hello {{first_name}}</p>"    },    "recipients": [      {        "email": "john@example.com",        "substitutions": {          "first_name": "John"        }      }    ]  }'
{
  "error_code": 0,
  "message": "OK",
  "request_id": "string",
  "queued_messages": 0,
  "messages": [
    {
      "error_code": 0,
      "message": "OK",
      "request_id": "string",
      "message_id": "string",
      "submitted_at": "2019-08-24T14:15:22Z",
      "to": "string"
    }
  ],
  "suppression_summary": {
    "status": "checked",
    "checked_recipients": 0,
    "accepted_recipients": 0,
    "suppressed_recipients": 0,
    "suppressed_emails": [
      "user@example.com"
    ]
  }
}
{
  "error_code": 0,
  "message": "string",
  "error": "missing_send_payload",
  "request_id": "string"
}
{
  "error_code": 0,
  "message": "string",
  "error": "missing_send_payload",
  "request_id": "string"
}
{
  "error_code": 0,
  "message": "string",
  "error": "missing_send_payload",
  "request_id": "string"
}
{
  "error_code": 0,
  "message": "string",
  "error": "missing_send_payload",
  "request_id": "string"
}
{
  "error_code": 0,
  "message": "string",
  "error": "missing_send_payload",
  "request_id": "string"
}
{
  "error_code": 0,
  "message": "string",
  "error": "missing_send_payload",
  "request_id": "string"
}
{
  "error_code": 0,
  "message": "string",
  "error": "missing_send_payload",
  "request_id": "string"
}

Send messages

Queue one or more complete email messages.

List domains GET

Next Page