Send API fundamentals

Use the Send API 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.