HTTPS API Commands

You can test all the TextMagic commands manually by entering their URLs into the address bar of your internet browser. TextMagic provides the following API commands:

Command	Description
send	send SMS command
account	check account balance command
message_status	retrieve SMS delivery notification
receive	receive incoming messages
delete_reply	delete incoming messages
check_number	check phone number

All these commands can be executed only if you provide a valid username and API password (get it here) in your requests. All TextMagic API commands (on a per-need basis) use the following key parameters:

Parameter name	Example
username	xxxx
password	yyyy
phone_number	447123456789

NOTE: You must enter your own username, password, and command name for each command to be executed. The phone number 447123456789 is only an example, and you must replace it with a valid phone number.

send

The send command is used to send an SMS message to a mobile phone. You can include up to 100 mobile phone numbers to a single send command, so if you need to send 2000 messages you need to complete 20 send commands.

Request

https://www.textmagic.com/app/api?username=xxxx&password=yyyy&cmd=send&text=Test+message&phone=447123456789&unicode=0

Response

{
    "message_id": {
        "8624389": "447123456789"
    },
    "sent_text": "Test message",
    "parts_count": 1
}

NOTES:

You must use a valid API username and password.
Each SMS is assigned a unique identifier that is necessary for checking that message’s delivery status. API users should take care to store message identifiers send command returns in order to be able to check those messages’ delivery status later on. The only means of obtaining message identifiers is by getting them from responses to send commands.

Request Parameters

Parameter	Description
username	Your TextMagic username
password	Your TextMagic API password (get it here)
text	The text message you are sending
phone	Your recipient’s phone number or recipients’ phone numbers. You can enter multiple phone numbers, each separated by a comma (,) without a space, and can include up to 100 phones in a single send request
unicode	You should set it to 1 if the message contains Unicode characters; otherwise you should set it to 0
from	Custom Sender ID
max_length	The maximum number of SMS parts which can be generated (up to 3). If this is omitted the default value of 3 is assumed.
cut_extra	0 (default) - if message length exceeds max_length parts, then "Very long message" error will be returned. 1 - if the message length exceeds max_length parts, then extra symbols will get cut off and everything that fits max_lengh will be sent.
send_time	This allows you to schedule message delivery for a specific time. This parameter’s value should be your desired delivery time, entered in one of the following formats: UNIX timestamp Time in UTC format (YYYY-MM-DDTHH:mm:ssZ) – this must be URL encoded, as must every other parameter. You can schedule messages to be sent up to 180 days later. If this parameter is not used TextMagic sends the message immediately. TextMagic API server time is always in the UTC/GMT time zone.

Response

Parameter	Description
message_id	This is a hash map of phone numbers, indexed by message identifiers which the gateway assigns to each sent message. You must save these identifiers if you want to retrieve your messages’ final delivery status.
sent_text	The text that was actually sent.
parts_count	The number of parts the message has.

account

You can use this command to check the current SMS credit balance on your account.

Request

https://www.textmagic.com/app/api?username=xxxx&password=testing&cmd=account

Response

{

"balance": 417.7
}

Request Parameters

Parameter	Description
username	Your TextMagic username.
password	Your TextMagic API password (get it here)

Response

Parameter	Description
balance	The amount of available SMS credits on your account.

message_status

This command allows you to retrieve the delivery status of any SMS you have already sent. When you give the message identifier the gateway generated and returned by send, this command returns any message’s details along with its current status.. Delivery Codes explained.

Request

https://www.textmagic.com/app/api?username=xxxx&password=testing&cmd=message_status&ids=8624390

Response

{
    "8624390": {
        "text": "sent message example text",
        "status": "d",
        "created_time": 1239869646,
        "reply_number": "447624800500",
        "credits_cost": 0.5,
        "completed_time": 1239869746
    }
}

Request Parameters

Parameter	Description
username	Your TextMagic username.
password	Your TextMagic API password (get it here).
ids	The identifier of any message returned by send command for which you want to check the status. If you want to check the status of several messages at once, enter their IDs with a comma without spaces separating each; for example, 8624389,8624390,8624391. TextMagic allows up to 100 IDs for each message_status request.

Response

The response is a hash map with your message details indexed by message identifiers. The message details object has the following fields:

Parameter	Description
text	Text message content.
status	The message’s current status.
created_time	The time TextMagic sent the message, as the gateway recorded it upon receiving your send request. The time value format is Unix time.
reply_number	Gateway’s reply number associated with the message. You can manage your reply options at any time.
credits_cost	Cost of the message in SMS credits. TextMagic only returns this parameter if the message is in final status.
completed_time	The time your message achieves final status, returned by the mobile operator. The time-value format is Unix time.

NOTE: We advise you to set up Callback URL for message_status. This way you can ensure that TextMagic posts your SMS delivery status to your application instantly.

receive

This command retrieves the incoming SMS messages from the server. You can request any SMS sent to one of our SMS reply numbers by using this API.

The server is limited to returning a maximum of 100 messages for each request. Please use last_retrieved_id parameter to page through your inbox.

Request

https://www.textmagic.com/app/api?username=xxxx&password=yyyy&cmd=receive&last_retrieved_id=1775795

Response

{
    "messages": [
        {
            "message_id": 1775796,
            "from": "447123456789",
            "timestamp": 1199867260,
            "text": "My reply!"
        }
    ],
    "unread": 0
}

Request Parameters

Parameter	Description
username	Your TextMagic username.
password	Your TextMagic API password (get it here)
last_retrieved_id	This allows you to page through the inbox. The server will only return messages with identifiers greater than last_retrieved_id. Set this parameter to 0 to fetch up to the first 100 replies from your inbox.

Response

Parameter	Description
messages	The array of incoming SMS messages. The server returns up to 100 messages.
unread	The number of messages with identifiers greater than last_retrieved_id remaining unreturned due to the limit on returned messages per request.

Each SMS object returned in messages array has the following fields:

Parameter	Description
message_id	The identifier of the incoming message.
from	The sender’s phone number.
timestamp	The message’s reception time expressed in Unix time format.
text	The message’s text.

NOTE: We advise you to set up Callback URL for receiving messages. This way you can ensure that TextMagic posts your incoming SMS messages to your application instantly.

delete_reply

This command helps you to delete any incoming SMS messages from the server. After you have read incoming messages sent to one of our SMS reply numbers you can delete them so the receive function will not return them anymore.

Request

https://www.textmagic.com/app/api?username=xxxx&password=yyyy&cmd=delete_reply&ids=1775796,1775797

Response

{
    "deleted": [
        1775796,
        1775797
    ]
}

Request Parameters

Parameter	Description
username	Your TextMagic username.
password	Your TextMagic API password (get it here)
ids	The identifier of the message that is to be deleted. If you want to delete several messages at once, enter their IDs separated by a comma without spaces, for example 1775796,1775797,1775798. You can delete up to 100 items in a single delete_reply request.

Response

Parameter	Description
deleted	An array showing the identifiers of the messages that have been deleted.

NOTE: After you have deleted incoming message, there is no way to revert the operation. Please use it carefully.

check_number

This command helps you to validate a phone number’s format and to check a message’s price to its destination. It also returns the phone number’s country code.

Request

https://www.textmagic.com/app/api?username=xxxx&password=yyyy&cmd=check_number&phone=447123456789

Response

{
    "447123456789": {
        "price": 0.8,
        "country": "GB"
    }
}

Request Parameters

Parameter	Description
username	Your TextMagic username.
password	Your TextMagic API password (get it here)
phone	Phone number to be checked. You can enter multiple phone numbers by separating each with a comma (,) without a space after it.

Response

The response contains a hash map of phone-number details indexed by the phone numbers. The objects of phone-number details have the following fields:

Parameter	Description
price	The cost in SMS credits of sending a single message to the number.
country	The number’s country code