View Your Sent Messages and Sessions
One SMS session is processed and billed as solid object. In this chapter you will see how to manage existing sessions and the messages they contain.
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 |
|
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:
|
| 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.
