---
title: "Queue up to 1000 SMS or MMS messages and report per-message refusals"
method: POST
path: "/v2/send/bulk"
tags: ["send-v2"]
---

# Queue up to 1000 SMS or MMS messages and report per-message refusals

`POST /v2/send/bulk`

## Request

- Base URL: `https://api.tracklysms.com/api`
- URL: `https://api.tracklysms.com/api/v2/send/bulk`
- Auth: API key in header `X-Api-Key`

## Request body

- BulkSendRequest
  - `messages` SendRequest[], required: Array of messages (max 1000)
    - `body` string: Required for SMS; optional MMS caption, at most 4096 characters
    - `contact_data` object: Optional contact data for macro substitution (first_name, last_name, custom_fields, timezone). {{contactId}} and {{listContactId}} are filled by Trackly from the recipient's list subscription.
    - `interstitial` object: Custom interstitial page shown before this message's tracked links redirect; implies interstitialMode=custom and must not be empty. Keys: auto_redirect, cta, description, meta_description, meta_favicon, meta_image, meta_title, redirect_text, title. meta_favicon is limited to 4096 UTF-8 bytes on this endpoint.
      - `auto_redirect` boolean
      - `cta` string
      - `description` string
      - `meta_description` string
      - `meta_favicon` string: Absolute http(s) URL or inline SVG markup, at most 4096 UTF-8 bytes.
      - `meta_image` string, uri
      - `meta_title` string
      - `redirect_text` string
      - `title` string
    - `interstitialMode` 'none' | 'list_default' | 'custom': Interstitial page for every tracked link in this message, customUrl links included: none, list_default (the sending list's default page) or custom (requires interstitial). Overrides the referenced SMS offer's own setting; omit to keep it. Requires wrap_links=true and a {{linkN}} placeholder backed by linkOverrides.
    - `linkOverrides` object: Per-placeholder link targets, keyed link1..link99 (max 10). Each entry sets exactly one of: offerId, partnershipOfferId, customUrl. Requires wrap_links=true. In sandbox the overrides are validated but no links are minted.
      - `link1` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link10` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link11` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link12` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link13` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link14` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link15` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link16` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link17` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link18` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link19` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link2` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link20` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link21` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link22` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link23` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link24` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link25` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link26` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link27` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link28` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link29` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link3` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link30` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link31` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link32` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link33` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link34` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link35` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link36` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link37` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link38` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link39` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link4` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link40` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link41` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link42` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link43` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link44` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link45` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link46` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link47` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link48` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link49` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link5` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link50` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link51` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link52` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link53` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link54` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link55` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link56` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link57` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link58` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link59` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link6` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link60` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link61` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link62` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link63` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link64` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link65` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link66` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link67` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link68` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link69` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link7` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link70` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link71` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link72` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link73` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link74` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link75` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link76` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link77` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link78` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link79` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link8` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link80` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link81` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link82` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link83` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link84` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link85` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link86` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link87` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link88` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link89` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link9` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link90` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link91` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link92` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link93` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link94` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link95` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link96` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link97` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link98` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
      - `link99` object
        - `customUrl` string
        - `offerId` string
        - `partnershipOfferId` string
    - `list_number` string, required: Sending list phone number (E.164 format)
    - `media` MMSMedia[]: Nonempty attachments array selects MMS; omit for SMS. Media and subject metadata may total at most 512 KiB
      - `content_id` string: Optional unique ASCII attachment content identifier
      - `content_type` string: Optional MIME type
      - `url` string, required: Public HTTPS media URL
    - `metadata` object: Optional metadata dict
    - `subject` string: Optional MMS subject; requires media
    - `to` string, required: Recipient phone number (E.164 format)
    - `wrap_links` boolean: Wrap URLs in link shortener

## Response `201`

Messages queued

- BulkSendResponse
  - `error_count` integer, required: Number of messages that failed
  - `errors` BulkErrorItem[], required: Array of error details
    - `code` string: Machine-readable error code
    - `error` string: Human-readable error
    - `errorCode` string: UPPER_SNAKE code; present only on queue-publish failures
    - `index` integer: Zero-based index of the failed message
    - `message_id` string: Orphaned MessageSent id; present only on queue-publish failures
    - `to` string: Recipient phone number
  - `queued_count` integer, required: Number of messages queued

## Other responses

- `400`: Validation error
- `401`: Authentication error
- `403`: Account or API key send policy forbids this request, or linkOverrides arm is not enabled
- `413`: Too many messages
- `429`: API key daily send policy cap exceeded
- `502`: Every message failed to queue, or short-link persistence failed — two body shapes, see the schema
- `503`: Send policy or service unavailable, or rejected messages could not be durably terminalized — two body shapes, see the schema

---

[API](https://skmtc.dev/tracklysms/apis/trackly-sms-api.md) · [All operations](https://skmtc.dev/tracklysms/apis/trackly-sms-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tracklysms/apis/trackly-sms-api/revisions/ac1ad22cb2a9?raw)