Send API fundamentals

Use the Send API at https://delivery.qboxmail.com to send email over HTTP through an existing Delivery account. It checks the message, reserves quota, queues delivery, and returns message details.

Available send modes

How sending works

1. A Delivery account, sending domain, and Send API token already exist.
2. Your application calls /v1/send or /v1/send/bulk with that Send API bearer token.
3. The API validates the token, IP policy, payload, rate limit, and quota.
4. The API performs a suppression-list pre-check to estimate accepted recipients.
5. The API reserves quota counters.
6. The API queues messages asynchronously.
7. The API returns 202 Accepted with request_id, message_id, and suppression_summary.
8. Workers compose and hand off messages to the delivery pipeline.
9. Final delivery events are visible through Delivery TraceMail.

/v1/send

Use /v1/send when each message already contains its final recipients and content.

{
  "messages": [
    {
      "from": "sender@example.com",
      "to": ["john@example.com"],
      "subject": "Hello",
      "text_body": "Hello from Qboxmail Delivery"
    }
  ]
}

Use a batch when you need to queue multiple different messages in one request.

/v1/send/bulk

Use /v1/send/bulk when one base message should be rendered for many recipients.

{
  "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"
      }
    }
  ]
}

Bulk templates use Handlebars-style variables such as {{first_name}}. The special {{email}} variable is always available.

By default, strict_substitutions is enabled: each recipient must provide every variable used by the template. Set options.strict_substitutions to false only when missing variables may safely render as empty strings.

Response shape

Successful Send API responses look like this:

{
  "error_code": 0,
  "message": "OK",
  "request_id": "f43eb659-beb4-4f8a-a737-2d403998f4cf",
  "queued_messages": 1,
  "messages": [
    {
      "error_code": 0,
      "message": "OK",
      "request_id": "f43eb659-beb4-4f8a-a737-2d403998f4cf",
      "message_id": "8a16f3df-7f5f-4e53-a7e7-3e665ef57c51@example.test",
      "submitted_at": "2026-04-16T08:41:13.225Z",
      "to": "john@example.com"
    }
  ],
  "suppression_summary": {
    "status": "checked",
    "checked_recipients": 1,
    "accepted_recipients": 1,
    "suppressed_recipients": 0,
    "suppressed_emails": []
  }
}

Store request_id and message_id. They are the fastest way to correlate application logs with TraceMail and support investigations.