Manage sending sessions

When you send an SMS to more than one recipient, it is collected as one message session. However, the text in your messages (in one session) may vary and you can send personalized texts using Templates. But first, let’s learn how to manage SMS sessions via the TextMagic API.

Get all sessions

To get all sessions, use:

GET /api/v2/sessions

with these parameters:

Name Required? Example Description
page No

3

Fetch the specified results page. The default is 1.

limit No 25 The number of results per page. The default is 10.

You will receive this standard paginated response:

Parameter Example Description
page 3 The current fetched page.
limit 25 Show the value of limit that you used with GET.
pageCount 150 The total number of pages.
resources Array of session responses See next section for session resource format details.

This list contains all of your sessions, including those which were sent but not via API.

Get a specific session’s details

To get details from a single session, use:

GET /api/v2/session/{id}

where id is a session ID. Note, this command has no parameters.

The response you receive will have the format:

Parameter Example Description
id 4991 Session ID.
startTime 2015-06-19T09:48:24+0000 Session creation time.
text Hello {First name}! Session text. If a template was used for the session text (see Messages: Send for details), it may contain template tags.
price 3.45 Session cost (in account currency).
source O Session origin:
numbersCount 18 Session recipient count.
referenceId my_reference_id_4991 Custom reference ID (see Messages: Send for details).

Delete a session

To delete a single session, use the following command:

DELETE /api/v2/sessions/{id}

where id is the session ID. Note, this command has no parameters. If successful, this command will return the standard delete response (204 No Content), otherwise it will return the standard error response.

You will not be refunded for any deleted sent sessions.

Get messages sent during a specific session

To get messages sent during a specific session use:

GET /api/v2/sessions/{id}/messages

where id is the session ID. Provide these parameters:

Name Required? Example Description
page No 3 Fetch the specified results page. The default is 1.
limit No 25 The number of results per page. The default is 10.

You will receive the standard paginated response:

Parameter Example Description
page 3 The current fetched page.
limit 25 The number of results per page.
pageCount 150 The total number of pages.
resources Array of message resources See next section for message resource format details.

Managing sent messages

Get all sent messages

To get all sent messages, not grouped by session, use:

GET /api/v2/messages

with the parameters:

Name Required? Example Description
page No 3 Fetch the specified results page. The default is 1.
limit No 25 The number of results per page. The default is 10.

You will receive the standard paginated response:

Parameter Example Description
page 3 The current fetched page.
limit 25 The number of results per page.
pageCount 150 The total number of pages.
resources Array of message resources See next section for message resource format details.

Get a specific message details

To get a single message, use:

GET /api/v2/messages/{id}

where id is a message ID. Note, this command has no parameters.

The response format you will receive is:

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

Message delivery statuses

Below you’ll find several delivery statuses for sent messages, which are divided into two types:

  • Intermediate – temporary statuses that can change as the messages are processed.
  • Final – these statuses are final and will not change.
Delivery status Type Description
a intermediate The mobile operator has acknowledged the message.
b intermediate The mobile operator has queued the message.
d final The message has been successfully delivered to the handset.
e final An error occurred while sending the message.
f final An error occurred while delivering the message.
j final The mobile operator has rejected the message.
q intermediate The message is queued on the TextMagic server.
r intermediate The message has been sent to the mobile operator.
s intermediate This message is scheduled to be sent later.
u final The status is unknown.

Delete a message

To delete a single message, use:

DELETE /api/v2/messages/{id}

where id is session ID. Note, this command has no parameters. If successful, this command will return the standard delete response (204 No Content), otherwise you will receive the standard error response.

You will not be refunded for any deleted sent messages.

The next step

Now you are ready to manage sent messages and sessions, please check our Messages: Receive section to learn how to receive and manage inbound SMSs via the TextMagic API.