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

 

Name Required? Examples Description
text Supply text or templateId or both. TextMagic test message The message text. Just like the other parameters, this should be urlencoded. It may contain any UTF-8 characters (Note: not all cell phone operators support UTF-8 characters). Check the encoding section for details.
templateId 55313 The message template ID. The Custom fields from the contacts will be filled by the selected template.
contacts Need at least one from contacts, lists or phones. 318,395,3348015 Send a message to this list of contacts. Note, the contact IDs should be separated by commas.
lists 10541,18599 Send a message to the contacts in these contact lists. Note, the list IDs should be separated by commas.
phones 447860021130,34911061252,491771781422 Send a message to this list of phone numbers in international E.164 format without the leading plus sign.
Note, the phone numbers should be separated by commas.
sendingTime No

1435649169
(for 06/30/2015 7:26am UTC)

Schedule a message to be sent at the specified time. The time should be in the UNIX timestamp format.
cutExtra No 1 The API cuts extra characters from the SMS text (i.e. because the text does not fit the partsCount) or returns 400 Bad request response. The default is 0 (false).
partsCount No 3 Maximum message parts count (per one recipient) you want to send during the session. We allow the sending of 1 to 6 message parts. The default is 6.
referenceId No my_custom_reference_413842 Custom message reference ID. This will be attached to Callbacks. You can use your internal IDs to identify the DLRs more easily.
from No

Textmagic

447624800500

One of the allowed sender settings (phone number or alphanumeric sender ID). If specified, the sender ID may be prohibited from some destinations, and a fallback default sender ID will then be used to ensure delivery. If not specified, the default sender settings will be used according to the recipient’s country code.
rrule No

FREQ=DAILY;INTERVAL=2;COUNT=5;
(to send message 5 times every 2 days)

Sending recurrence rule: iCal RRULE parameter. When specified, the sendingTime is mandatory and will be used as a starting point for the first message sent.
Don’t worry about duplicate contacts. If you have duplicate contacts or phone numbers, we will still send your message to that person, but will do so only once (during that sending session).

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:

Parameter
Example
Description
id

49576009

The main returned resource ID ( message, session, bulk or schedule)
href /api/v2/messages/49576009 A link to the main returned resource. id and href are here for compatibility with the standard link response.
type session The main returned resource type: message, session, bulk, or schedule.
sessionId 34436600 Sending session ID. Could be null if it is a bulk sending session (more than 1,000 recipients).
bulkId 357122 The bulk sending session ID. Set if the current session contains more than 1,000 recipients.
messageId 49576009 The message ID (not session). Set if the session contains only one message.
scheduleId 313 The schedule ID. Set if one or both of the sendingTime and rrule parameters are supplied.

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:

Parameter
Value
text I love TextMagic
(don’t forget to urlencode your string!)
phones 447860021130

You will receive a result like this:

Parameter
Example
id 49576009
href /api/v2/messages/49576009
type message
sessionId 34436600
bulkId null
messageId 49576009
scheduleId null

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:

Parameter
Value
text Hello, how are you?
lists 55314
phones 447860021130,447860021131,447860021132,447860021134
contacts 318,395,3348015

You will receive a result like this:

Parameter
Example
id 357122
href /api/v2/sessions/357122
type session
sessionId 357122
bulkId null
messageId null
scheduleId null

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:

Parameter
Value
templateId 10541
lists 55315

You will receive a result like this:

Parameter
Example
id 357122
href /api/v2/bulks/357122
type bulk
sessionId null
bulkId 357122
messageId null
scheduleId null

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:

Parameter
Value
templateId 10541
lists 55313

You will receive a result like this:

Parameter
Example
id 34436613
href /api/v2/sessions/34436613
type session
sessionId 34436613
bulkId null
messageId null
scheduleId null

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.

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.

Your server should reply with a 200 OK response at this URL. If it does not, your callback URL will be treated as invalid and the inbound messages will not be passed to your application.

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.

Parameter Example Description
id 4991 Message ID.
sender 447624800500 Message sender (phone number or alphanumeric Sender ID).
receiver 447860021130 Recipient phone number.
text Hello John! Message text (after tags substitution, if any).
price 0.25 Message cost (in account currency).
status d Delivery status of the message.
Please see the table at the Sessions section to see different delivery statuses.
partsCount 2 Message parts (multiples of 160 characters) count.
messageTime 2015-06-19T09:48:24+0000 Sending time.
charset UTF-16BE Message charset. Could be:
  • ISO-8859-1 for plaintext SMS

  • UTF-16BE for Unicode SMS

firstName John Contact first name. Could be substituted from your Contacts (even if you submitted phone number instead of contact ID).
lastName Conway Contact last name.
country DK Two-letter ISO country code of the recipient phone number.
referenceId my-reference-id-319 Custom message reference ID. You can use your internal IDs to identify the DLRs more easily when doing POST /api/v2/messages.

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.