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:

NameRequired?ExampleDescription
pageNo

3

Fetch the specified results page. The default is 1.

limitNo25The number of results per page. The default is 10.

You will receive this standard paginated response:

ParameterExampleDescription
page 3The current fetched page.
limit25Show the value of limit that you used with GET.
pageCount150The total number of pages.
resourcesArray of session responsesSee 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:

ParameterExampleDescription
id4991Session ID.
startTime 2015-06-19T09:48:24+0000Session creation time.
textHello {First name}!Session text. If a template was used for the session text (see Messages: Send for details), it may contain template tags.
price3.45Session cost (in account currency).
sourceO Session origin:
numbersCount18Session recipient count.
referenceIdmy_reference_id_4991Custom 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:

NameRequired?ExampleDescription
pageNo 3 Fetch the specified results page. The default is 1.
limitNo25The number of results per page. The default is 10.

You will receive the standard paginated response:

ParameterExampleDescription
page 3The current fetched page.
limit25The number of results per page.
pageCount150The total number of pages.
resourcesArray of message resourcesSee 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:

NameRequired?ExampleDescription
pageNo 3 Fetch the specified results page. The default is 1.
limitNo25The number of results per page. The default is 10.

You will receive the standard paginated response:

ParameterExampleDescription
page 3The current fetched page.
limit25The number of results per page.
pageCount150The total number of pages.
resourcesArray of message resourcesSee 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:

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

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 statusTypeDescription
aintermediateThe mobile operator has acknowledged the message.
bintermediateThe mobile operator has queued the message.
dfinalThe message has been successfully delivered to the handset.
efinalAn error occurred while sending the message.
ffinalAn error occurred while delivering the message.
jfinalThe mobile operator has rejected the message.
qintermediateThe message is queued on the TextMagic server.
rintermediateThe message has been sent to the mobile operator.
sintermediateThis message is scheduled to be sent later.
ufinalThe 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.