Getting started with Twilio Bulk Messaging

Before you begin, ensure you have the following:

1. A Twilio account: Sign up for a free account.
2. An approved and compliant phone number or sender for SMS, MMS, WhatsApp, or RCS in your target region(s).
3. Opt-out configuration according to your regional requirements. To configure advanced opt-out, see Customizing your users' opt-in and opt-out experience with Advanced Opt-Out. The Bulk Messaging API does not support this functionality natively.

The Bulk Messaging API uses basic authentication, like other Twilio APIs. To authenticate, include a Basic Authentication header whose username:password pair is your API key SID and API key secret.

To send a message, make a POST request to the Messages resource with from, to, and content parameters.

1
curl -X POST 'https://comms.twilio.com/v1/Messages' \
2
--header 'Content-Type: application/json' \
3
--data '{
4
    "from": {
5
        "address": "<Your Purchased Twilio Phone Number>",
6
        "channel": "SMS"
7
    },
8
    "to": [{
9
        "address": "+15558675310",
10
        "channel": "PHONE"
11
    }],
12
    "content": {
13
        "text": "What day is it?"
14
    }
15
}' \
16
-u $TWILIO_API_KEY:$TWILIO_API_SECRET

You can deliver the same message to up to 10,000 recipients in a single API request by adding more entries to the to array.

1
curl -X POST 'https://comms.twilio.com/v1/Messages' \
2
--header 'Content-Type: application/json' \
3
--data '{
4
    "from": {
5
        "address": "<Your Purchased Twilio Phone Number>",
6
        "channel": "SMS"
7
    },
8
    "to": [
9
        {
10
            "address": "+15558675310",
11
            "channel": "PHONE"
12
        },
13
        {
14
            "address": "+15558675311",
15
            "channel": "PHONE"
16
        }
17
    ],
18
    "content": {
19
        "text": "Ahoy!"
20
    }
21
}' \
22
-u $TWILIO_API_KEY:$TWILIO_API_SECRET

When describing who you are sending to, the possible values are:

• WHATSAPP
• PHONE: The phone represents the text messaging app on a user's device. This is the same identifier for both RCS and SMS/MMS messages.

When describing what numbers and addresses you are sending from, we split RCS and SMS, so that it is possible to specify when you want to use RCS, text message, or both. The possible values in those scenarios are:

• SMS
• RCS
• WHATSAPP

See the Messages API reference for more details.

After sending a message, especially to many recipients, retrieving the operation lets you monitor and manage the outcome, providing transparency and control over message delivery.

When you send a message with the Create Message endpoint, the response headers include an operationId. Use this value to track the delivery status of the message by sending a GET request to the Operations endpoint.

Request sample:

1
curl -X GET "https://comms.twilio.com/v1/Messages/Operations/comms_operation_01h9krwprkeee8fzqspvwy6nq8" \
2
-u $TWILIO_API_KEY:$TWILIO_API_SECRET

Sample response:

1
  {
2
  "id": "comms_operation_01h2xcejqtf2nbrexx3vqjhp41",
3
  "status": "COMPLETED",
4
  "stats": {
5
    "total": 1,
6
    "recipients": 1,
7
    "attempts": 1,
8
    "unaddressable": 0,
9
    "queued": 0,
10
    "sent": 0,
11
    "scheduled": 0,
12
    "delivered": 1,
13
    "read": 0,
14
    "undelivered": 0,
15
    "failed": 0,
16
    "canceled": 0
17
  },
18
  "createdAt": "2024-04-05T06:20:00Z",
19
  "updatedAt": "2024-04-05T06:20:00Z"
20
}

For more details, see the Operations API reference.

Now that you've sent your first message, see Operations and message tracking to learn how to track delivery status and monitor your campaigns.