SMS send resource

Overview

This endpoint allows sending transactional or campaign SMS messages to one or more recipients using Sendmachine’s Web API.

Authorization

See API overview.

Required scope: sms_send

Content-Type

application/json

Send SMS

Request

POST /sms/send

Request Body

{
    "personalization": [{
        "to": ["phone_number1", "phone_number2"]
    }],
    "message": "The SMS message content"
}

Success response

{
    "status": "accepted",
    "count": 10,
    "segments": 10,
    "request_id": "00000000-0000-0000-0000-000000000000"
}

Request

{
    "personalization": [{
        "to": [],
        "macros": {},
        "metadata": {}
    }],
    "message": "",
    "message_type": "",
    "campaign_name": "",
    "click_tracking": ""
}

Request Fields

Field	Type	Required	Description
personalization	array<object>	Yes	Message recipient configuration.
message	string	Yes	SMS content to be sent. Messages longer than 160 characters are split into segments of 153 characters.
message_type	string	No	Message type: transactional or campaign
campaign_name	string	No	Message name (used for transactional messages).
click_tracking	integer	No	Enable click tracking (1 or 0).

Personalization Object

Each object inside the personalization array represents a group of recipients sharing the same macros and metadata.

Field	Type	Required	Description
to	array<string>	Yes	Recipient phone numbers.
macros	object	No	Macros applied to the SMS content. See smtp_macros documentation.
metadata	object	No	Metadata sent with webhook requests.

Note

• Messages with type campaign are paused when sent in time range 22:00 - 07:00

• Duplicate recipients inside the same personalization entry are ignored.

Response

If the request is successful, the API will return a 202 Accepted status code, meaning that the request has been accepted for processing.

The response body will contain a JSON object with the following properties:

{
    "status": "accepted",
    "count": 10,
    "segments": 10,
    "request_id": "00000000-0000-0000-0000-000000000000"
}

Response Fields

Field	Type	Required	Description
status	string	Yes	Request processing status (e.g. accepted).
count	integer	Yes	Number of recipients accepted for sending.
segments	integer	Yes	Total number of SMS segments to be sent.
request_id	string	Yes	Unique request identifier (UUID).

Response status and codes

HTTP Code	Status	Description
202	accepted	Message accepted for delivery.
400	validation_error	Request validation failed. See error codes below.
401	denied	Authentication failed or access denied.
500	error	Internal server error.
529	sendingspeed_exceeded	Sending speed limit exceeded.

400 Error Codes

The following error codes may be returned in a 400 response.

Error Code	Description
send_limit_reached	Sending limit has been reached.
rating_dropped	Sender rating dropped below allowed level.
invalid_json	Invalid JSON payload.
invalid_sender	Sender is invalid.
sender_not_active	Sender exists but is not active.
pers_limit_reached	Personalization limit exceeded.
invalid_recipient	Recipient phone number is invalid.
missing_personalization	Personalization data is missing.
invalid_type	Invalid message type.
invalid_macros	Provided macros are invalid.
invalid_metadata	Metadata format is invalid.
invalid_field_value	Field contains an invalid value.
field_value_overflow	Field value exceeds allowed size.
empty_field_value	Field value cannot be empty.
message_segments_overflow	Message exceeds allowed segment count.
missing_contract	Contract configuration missing.
missing_message	Message content missing.
invalid_message	Message content invalid.
invalid_message_encoding	Message encoding is invalid or unsupported.

Limitations

• The total number of recipients must be less than 100.

• The total number of personalizations must be less than 100.

Reserved data

When building the message data array please note that there are some reserved attributes.

• Reserved macros: date, year, unsub_link

Examples

cURL

curl -X POST https://api.sendmachine.com/sms/send \
-H "Content-Type: application/json" \
-u "YOUR_API_USERNAME:YOUR_API_KEY" \
-d '{
    "personalization": [{
        "to": ["phone_number1", "phone_number2"]
    }],
    "message": "The SMS message content"
}'

PHP

Send a message to specific recipients with custom macros:

<?php

$data = array(
    'personalization' => array(
        array(
            'to' => array('+40712345678', '+40787654321'),
            'macros' => array(
                'FIRST_NAME' => 'John',
                'LAST_NAME' => 'Doe',
            ),
        ),
    ),
    'message' => 'This is a test SMS message',
);

$jsondata = json_encode($data);

$ch = curl_init('https://api.sendmachine.com/sms/send');

curl_setopt($ch, CURLOPT_USERPWD, 'API_KEY:API_PASSWORD');
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsondata);

$response = curl_exec($ch);