Send Text Messages

The primary reason for using the Textmagic API is to send SMS text messages. This page describes the following details about sending messages:

Endpoint

To send messages using Textmagic API v2, send a POST request to the messages URL:

POST https://rest.textmagic.com/api/v2/messages

Parameters

 

Response

If your request is unsuccessful, you will receive an HTTP error code along with an error message. Otherwise, you will an HTTP success code (e.g. 200, 201, 204) and JSON response body with the following properties:

How to send a single text message

To send a simple text message to one recipient, you should set only the text and the phones parameters. text should contain that desired text and phones should be set to the recipient’s international phone number. For example, to send an SMS message with the text “I love Textmagic” to the phone number +44 (0) 7 860021130, use the command:

POST https://rest.textmagic.com/api/v2/messages

with the following parameters:

You will receive a result like this:

As long as you have sent a message to at least one recipient, the Textmagic API will return not only the session ID, but also the single message ID. Also, you can watch for the delivery status changes using this ID without fetching session messages first. Since this is not a bulk session or scheduled message, bulkId and scheduleId are null.

How to send bulk text messages

You can also send a message to many recipients simultaneously. Let’s see how it’s done in the example below.

Assuming that you have a list ID 55314 (with 100 recipients), write:

POST https://rest.textmagic.com/api/v2/messages

with the following parameters:

You will receive a result like this:

Sending more than 1,000 messages in one session

A Bulk session in Textmagic is when you send a message to more than 1,000 recipients. Since processing such a large session could take a long time (i.e. more than a few seconds), the messages are stored in a queue temporarily. You can check the progress of the messages by sending a GET to:

/api/v2/bulks/{id}

Assuming that you have list ID 55315 with more than 1,000 recipients, call:

POST https://rest.textmagic.com/api/v2/messages

with the following parameters:

You will receive a result like this:

As you can see, the session has not been created yet, since it will be created after processing all the contacts you supplied during request.

How to send a text message using an SMS template

Next, let’s try to send an SMS to a contact list using a message template instead of specifying the message text. An extra feature we can use is the Custom fields tags, which we can apply to send personalized texts to all recipients.

Assuming you have these items:

• A contact list with ID 10541 (with two or more contacts). You can use test number 999 .
• The message template with ID 55313 (with First name and Last name tags). When you sign up for a Textmagic account, you automatically receive several message templates, such as Callback request or Booking confirmation. You can use any of them.
• A sufficient balance in your account to send this SMS message to the contact list.

POST https://rest.textmagic.com/api/v2/messages

with the following parameters:

You will receive a result like this:

This is a sending session with more than one recipient (but less than 1,000); see the notes above about sending bulk messages. We cannot select just one message from this session, so the messageId is also empty. However, you can get the session for the messages and then fetch the messages one by one.

Delivery status callback

A callback is a mechanism that posts the JSON body of a sent message to the URL on a server that you specify. The server application which receives the callback can check the message status and trigger some actions based on that data.

Delivery status callback is triggered when SMS receives a final status. This is a complete list of final statuses:

• d – delivered;
• f – failed;
• j – rejected;
• u – unknown.

Here is how to set up the delivery status callback URL:

1. Log in to Textmagic (or start a free trial if you haven’t registered yet).
2. Go to the API page.
3. Enter your callback URL into the Callback URL for delivery notifications field.
4. Click the Test button to test your URL.
5. If it’s successful, click Save changes.

Call parameters

Your callback URL will be triggered immediately when sent message status changes. The parameters are passed by the POST method and contain the following information (i.e. exact copy of the message resource plus custom referenceId, if you have specified it when sending message via POST /api/v2/messages). The Resource format is basically the format of the reply when making the request to the specific API resource.

The next step

Congratulations! You can now use Textmagic API to send messages one at a time or in bulk. The Textmagic API also allows you to Receive text messages and Schedule recurring messages.