Skip to main content
POST
/
api
/
v1
/
meta-templates
/
send-bulk
/
curl -X POST https://api.mindosoftware.com/api/v1/meta-templates/send-bulk/ \
  -H "X-API-Key: mindo_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "813497231850626",
    "template_name": "welcome_message",
    "language": "es",
    "recipients": [
      {
        "phone": "+5491112345678",
        "variables": {
          "name": "Juan Perez",
          "code": "ABC123"
        },
        "button_variables": {
          "button_0": "ABC-123"
        }
      },
      {
        "phone": "+5491187654321",
        "variables": {
          "name": "Maria Garcia",
          "code": "DEF456"
        },
        "button_variables": {
          "button_0": "DEF-456"
        }
      },
      {
        "phone": "+5491199887766",
        "variables": {
          "name": "Carlos Lopez",
          "code": "GHI789"
        },
        "button_variables": {
          "button_0": "GHI-789"
        }
      }
    ]
  }'

{
  "bulk_send_id": "a3f2b8c9-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "task_id": "7f8e9d0c-1b2a-3c4d-5e6f-7a8b9c0d1e2f",
  "status": "queued",
  "template_name": "welcome_message",
  "total_recipients": 3,
  "unique_recipients": 3,
  "estimated_time_minutes": 0.4,
  "created_at": "2025-11-16T21:30:00Z",
  "whatsapp_phone_number": {
    "id": 123,
    "phone_number_id": "813497231850626",
    "display_phone_number": "+54 9 223 675-0780",
    "verified_name": "Mindo Software",
    "quality_rating": "GREEN",
    "messaging_limit_tier": "TIER_1000"
  },
  "quota_info": {
    "can_send": true,
    "quota_needed": 3,
    "quota_available": 997,
    "quota_total": 1000,
    "tier": "TIER_1000"
  }
}

​
Description

This endpoint allows you to send a WhatsApp template to multiple recipients in a single request. It implements an asynchronous pattern: when creating the send, it returns a bulk_send_id that you can use to check the progress of the send. The API automatically handles Meta’s rate limits based on the number’s tier, distributes the sends, and tracks the status of each individual message.

​
Authentication header

​
X-API-Key
string
required
Your Mindo API Key. Format: mindo_xxxxxxxxxxxxxxxxxxxxxxxx

​
Body parameters

​
phone_number_id
string
required
Meta’s WhatsApp phone number ID from which messages will be sent. You can get it from the Get business accounts endpoint.
​
template_name
string
required
Name of the approved template to send. Must have APPROVED status in Meta.
​
language
string
Template language. Default: "es". Examples: "es", "en", "pt_BR".
​
recipients
array
required
List of recipients with their custom variables.

​
Response (202 Accepted)

​
bulk_send_id
string (UUID)
Unique bulk send ID. Use to check progress with Send status.
​
task_id
string
Background processing task ID.
​
status
string
Initial send status. Always "queued" when created.
​
template_name
string
Name of the template to be sent.
​
total_recipients
integer
Total recipients in the submitted list.
​
unique_recipients
integer
Number of unique recipients after automatic deduplication.
​
estimated_time_minutes
float
Estimated processing time in minutes, based on the number’s tier.
​
created_at
string (ISO 8601)
Send creation date and time.
​
whatsapp_phone_number
object
Information about the WhatsApp number that will send the messages.
​
quota_info
object
Quota and send limit information.
curl -X POST https://api.mindosoftware.com/api/v1/meta-templates/send-bulk/ \
  -H "X-API-Key: mindo_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "813497231850626",
    "template_name": "welcome_message",
    "language": "es",
    "recipients": [
      {
        "phone": "+5491112345678",
        "variables": {
          "name": "Juan Perez",
          "code": "ABC123"
        },
        "button_variables": {
          "button_0": "ABC-123"
        }
      },
      {
        "phone": "+5491187654321",
        "variables": {
          "name": "Maria Garcia",
          "code": "DEF456"
        },
        "button_variables": {
          "button_0": "DEF-456"
        }
      },
      {
        "phone": "+5491199887766",
        "variables": {
          "name": "Carlos Lopez",
          "code": "GHI789"
        },
        "button_variables": {
          "button_0": "GHI-789"
        }
      }
    ]
  }'

{
  "bulk_send_id": "a3f2b8c9-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "task_id": "7f8e9d0c-1b2a-3c4d-5e6f-7a8b9c0d1e2f",
  "status": "queued",
  "template_name": "welcome_message",
  "total_recipients": 3,
  "unique_recipients": 3,
  "estimated_time_minutes": 0.4,
  "created_at": "2025-11-16T21:30:00Z",
  "whatsapp_phone_number": {
    "id": 123,
    "phone_number_id": "813497231850626",
    "display_phone_number": "+54 9 223 675-0780",
    "verified_name": "Mindo Software",
    "quality_rating": "GREEN",
    "messaging_limit_tier": "TIER_1000"
  },
  "quota_info": {
    "can_send": true,
    "quota_needed": 3,
    "quota_available": 997,
    "quota_total": 1000,
    "tier": "TIER_1000"
  }
}

​
Send statuses

The bulk send status field can have the following values:
StatusDescription
QUEUEDSend created and queued for processing
PROCESSINGActively sending messages
COMPLETEDAll messages processed successfully
PARTIALProcessed with some failures
FAILEDSend failed completely
CANCELLEDSend cancelled manually
Use the Send status endpoint with the bulk_send_id to check progress in real time, including counters for sent, delivered, read, and failed messages.

​
Automatic deduplication

The API automatically removes duplicate phone numbers from the recipients list. The unique_recipients field in the response indicates the actual number of unique recipients that will receive the message, while total_recipients reflects the original count submitted.

​
Use cases

Send a personalized welcome message to a list of newly registered customers.
import requests

new_customers = [
    {"phone": "+5491112345678", "name": "Juan Perez"},
    {"phone": "+5491187654321", "name": "Maria Garcia"},
    {"phone": "+5491199887766", "name": "Carlos Lopez"},
]

response = requests.post(
    "https://api.mindosoftware.com/api/v1/meta-templates/send-bulk/",
    headers={"X-API-Key": "mindo_xxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "phone_number_id": "813497231850626",
        "template_name": "welcome_message",
        "recipients": [
            {"phone": c["phone"], "variables": {"name": c["name"]}}
            for c in new_customers
        ]
    }
)

bulk = response.json()
print(f"Send created: {bulk['bulk_send_id']}")
print(f"Recipients: {bulk['unique_recipients']}")
Send unique verification codes to each recipient.
import requests
import secrets

users = [
    {"phone": "+5491112345678", "name": "Juan"},
    {"phone": "+5491187654321", "name": "Maria"},
]

recipients = [
    {
        "phone": user["phone"],
        "variables": {
            "name": user["name"],
            "code": secrets.token_hex(3).upper()
        }
    }
    for user in users
]

response = requests.post(
    "https://api.mindosoftware.com/api/v1/meta-templates/send-bulk/",
    headers={"X-API-Key": "mindo_xxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "phone_number_id": "813497231850626",
        "template_name": "verification_code",
        "recipients": recipients
    }
)
Notify multiple customers about updates to their orders.
const orders = [
  { phone: "+5491112345678", orderId: "ORD-001", status: "Shipped" },
  { phone: "+5491187654321", orderId: "ORD-002", status: "In transit" },
  { phone: "+5491199887766", orderId: "ORD-003", status: "Delivered" },
];

const response = await fetch(
  "https://api.mindosoftware.com/api/v1/meta-templates/send-bulk/",
  {
    method: "POST",
    headers: {
      "X-API-Key": "mindo_xxxxxxxxxxxxxxxxxxxxxxxx",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      phone_number_id: "813497231850626",
      template_name: "order_update",
      recipients: orders.map(o => ({
        phone: o.phone,
        variables: { order_id: o.orderId, status: o.status }
      }))
    })
  }
);

const data = await response.json();
console.log(`Send ${data.bulk_send_id} created for ${data.unique_recipients} recipients`);
Send personalized reminders with event date and time.
import requests

attendees = [
    {"phone": "+5491112345678", "name": "Juan Perez"},
    {"phone": "+5491187654321", "name": "Maria Garcia"},
]

response = requests.post(
    "https://api.mindosoftware.com/api/v1/meta-templates/send-bulk/",
    headers={"X-API-Key": "mindo_xxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "phone_number_id": "813497231850626",
        "template_name": "event_reminder",
        "recipients": [
            {
                "phone": a["phone"],
                "variables": {
                    "name": a["name"],
                    "event_name": "Webinar: API Introduction",
                    "event_date": "November 28, 6:00 PM"
                }
            }
            for a in attendees
        ]
    }
)

bulk = response.json()
print(f"Reminders sent: {bulk['unique_recipients']}")
print(f"Estimated time: {bulk['estimated_time_minutes']} minutes")