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

 

NameRequired?ExamplesDescription
textSupply 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.
templateId55313 The message template ID. The Custom fields from the contacts will be filled by the selected template.
contactsNeed at least one from contacts, lists or phones.318,395,3348015Send a message to this list of contacts. Note, the contact IDs should be separated by commas.
lists10541,18599Send 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.
sendingTimeNo

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.
cutExtraNo1The 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).
partsCountNo3Maximum 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.
referenceIdNomy_custom_reference_413842Custom message reference ID. This will be attached to Callbacks. You can use your internal IDs to identify the DLRs more easily.
fromNo

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.
rruleNo

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.
typesession The main returned resource type: message, session, bulk, or schedule.
sessionId34436600Sending session ID. Could be null if it is a bulk sending session (more than 1,000 recipients).
bulkId357122The bulk sending session ID. Set if the current session contains more than 1,000 recipients.
messageId49576009The message ID (not session). Set if the session contains only one message.
scheduleId313 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
id49576009
href/api/v2/messages/49576009
typemessage
sessionId34436600
bulkIdnull
messageId49576009
scheduleIdnull

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?
lists55314
phones447860021130,447860021131,447860021132,447860021134
contacts318,395,3348015

You will receive a result like this:

Parameter
Example
id 357122
href /api/v2/sessions/357122
typesession
sessionId357122
bulkId null
messageIdnull
scheduleIdnull

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
lists55315

You will receive a result like this:

Parameter
Example
id 357122
href /api/v2/bulks/357122
typebulk
sessionIdnull
bulkId 357122
messageIdnull
scheduleIdnull

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
templateId10541
lists55313

You will receive a result like this:

Parameter
Example
id 34436613
href /api/v2/sessions/34436613
typesession
sessionId34436613
bulkIdnull
messageIdnull
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.

ParameterExampleDescription
id4991Message 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).
price0.25Message cost (in account currency).
statusd Delivery status of the message.
Please see the table at the Sessions section to see different delivery statuses.
partsCount2Message parts (multiples of 160 characters) count.
messageTime 2015-06-19T09:48:24+0000Sending time.
charsetUTF-16BE Message charset. Could be:
  • ISO-8859-1 for plaintext SMS

  • UTF-16BE for Unicode SMS

firstNameJohnContact first name. Could be substituted from your Contacts (even if you submitted phone number instead of contact ID).
lastNameConwayContact last name.
countryDKTwo-letter ISO country code of the recipient phone number.
referenceIdmy-reference-id-319Custom 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.