Technical Overview

Sign-up for free and set up your default settings (API and Defaults). This will provide you with an API key. Calls to the API need to be authenticated. For each API call you can either pass your username and password as parameters (less secure) or your API key (more secure). If you think your API key has been compromised, you can generate a new one from your API settings.

All API examples and URIs used in this document are non-operational. Please sign-up for a free account and generate your API key to be able to test these API methods in full. Credit might be required for Send operations. Make sure your systems are in line with the latest API specifications. Planned updates to our API will be communicated via email.
More

API Overview

URI structure, response format and error codes
More

Error Codes

Codes returned by this API
More

Authentication

Authentication methods accepted by this API

Overview

(Top)

This API provides you with all the relevant messaging operations: sending, retrieve delivery reports (push/pull) and balance checks

URI Structure

All Targlets API requests start with https://targlets.com/api - followed with the operation required

  • Send: send text messages

    https://targlets.com/api/Send...

  • Delivery Reports: pull delivery reports for specific jobs

    https://targlets.com/api/DeliveryReports...

  • Balance: check balance for specific rates

    https://targlets.com/api/Balance...

Response Format

Targlets API responses can either be Ok or Error Json objects

Ok Example

                        
                                {
                                    "Ok":
                                    {
                                        "RateId":"62be8079-b370-42f8-a1e3-ebbd2c7d216d",
                                        "Balance":"50.00"
                                    }
                                }
                            
                        

Error Example

                         
                                {
                                    "Error":
                                    {
                                        "Code":"107",
                                        "Message":"Authentication failed"
                                    }
                                }
                            
                        

Error codes

(Top)

An outline of error codes returned by this API.

Code Description Notes
100 Missing fields - Either APIKey is malformed or Username and Password are missing API requests require one of the following: APIKey or Username/Password
101 There is at least one missing field ([missing-fields]) All required parameters need to be supplied
102 Message cannot exceed 612 characters N/A
103 Recipient list is malformed, please use a comma separated list of numeric destinations N/A
104 Invalid Sender Identifier Alphanumeric sender ID cannot be longer than 11 characers, while numeric has a maximum of 15 numbers. Spaces and special characters are not allowed
105 Invalid Message Type Message types can either be set to 0 (normal text message) or 1 (flash/popup text message)
106 Rate Id is malformed Rate Id should be a valid GUID
107 Authentication failed This error code may be returned if a) APIKey submitted is not found [APIKey is not found] or b) Username/Password provided are not valid
108 Recipient list contains invalid numbers. Rate chosen requires all numbers to start with [Country Code] If the rate selected is country specific, all recipients must include the respective country code
109 Insufficient credit for rate: [Rate Id] You do not have enough credit (on a specific rate) to submit this job
110 You have not purchased any credits for rate: [Rate Id] You do not have any credit for the specified rate
111 Rate [Rate Id] does not exist N/A
112 Internal Server Error An exception occured and the job cannot be processed
113 Job Id is malformed Job Id should be a valid GUID
114 The Job ID requested was not sent using the given username Delivery report requests are only allowed for jobs sent using the specified credentials
115 Job is still in queue Delivery reports cannot be supplied at this stage because the job is still pending processing
116 The minutesfromnow parameter is malformed The minutesfromnow parameter must be a valid double value
117 A default time zone is required for scheduled jobs. Please modify your API and Default settings at https://targlets.com
118 Too many recipients in the job A maximum of 15000 recipients is allowed per job

Authentication

(Top)

This API requires authenticated requests. In both cases you need to sign-up for an account. There are two authentication methods:

  1. Username/Password: API requests should include username and password parameters
    • Example: https://targlets.com/api/DeliveryReports?username=user@email.com&password=12345678&...
  2. API Key: API requests should include the apikey parameter
    • Example: https://targlets.com/api/DeliveryReports?apikey=c7ce30e0-954b-49ea-ab25-fb7ad4d9dddd&...

Methods

(Top)

The following sections will describe all the methods available, together with input parameters and expected results.

/Send

(Top)

This POST method allows you to send single and bulk text messages. Scheduling and message type can be specified in the parameter list.

Method

URI HTTP Method Authentication
https://targlets.com/api/Send POST Username/Password or APIKey

Request Parameters

Parameter Type Description Required?
username String Email address with which you registered No
password String Password associated with the provided email address No
apikey GUID API Key generated after first login. You may retrieve this from the API and Defaults section within the dashboard. Click here to register for a free account. No
recipients String A comma delimited list of recipient numbers (these should also include the country code) i.e. 44XXXXXXX,356XXXXXXX,39XXXXXXXX Yes
senderid String Sender identifier to use for this job. This will replace the From attribute for each text message Yes
message String Text message body. This may not exceed 612 characters Yes
type bit Set to 0 for normal text message format and 1 for flash/popup message format Yes
rateid GUID This specifies the rate to use for this particular job. You may purchase credits from different rates (e.g. country specific). You will find the API key for each rate from the Balances and Alerts section. Yes
minutesfromnow Double This specifies the delay (in minutes) before this message is sent. This parameter requires a default time zone which is specified upon first login No

Response (Ok)

Response field Type Description Notes
Code String Response code 200 (Ok)
JobId GUID A unique identifier for the successfully created job This identifier can be used for delivery report queries

Example

                            
                                {
                                    "Ok":
                                    {
                                        "Code":"200",
                                        "JobId":"c2924a89-c674-4c25-a1f8-dcc233e33b02"
                                    }
                                }
                            
                        

/DeliveryReports

(Top)

You can retrieve delivery reports in two ways, using either the Push or Pull method.

Pull Method

This GET method allows you to retrieve delivery reports for a specific Job using the JobId.

URI HTTP Method Authentication
https://targlets.com/api/DeliveryReports GET Username/Password or APIKey

Request Parameters

Parameter Type Description Required?
username String Email address with which you registered No
password String Password associated with the provided email address No
apikey GUID API Key generated after first login. You may retrieve this from the API and Defaults section of your dashboard. Click here to register for a free account. No
jobid GUID This specifies the job for which you want to retrieve the latest delivery reports. Yes

Response (Ok)

Response field Type Description Notes
Awaiting String[] An array listing recipients for whom delivery reports are still pending from the respective mobile operator [{"MSISDN":"44XXXXXXXX"},{"MSISDN":"39XXXXXXXX"},{"MSISDN":"356XXXXXXXX"}]
Delivered String[] An array listing recipients who have successfully received the text message [{"MSISDN":"44XXXXXXXX"},{"MSISDN":"39XXXXXXXX"},{"MSISDN":"356XXXXXXXX"}]
Undelivered String[] An array listing invalid recipients [{"MSISDN":"44XXXXXXXX"},{"MSISDN":"39XXXXXXXX"},{"MSISDN":"356XXXXXXXX"}]
Expired String[] An array listing recipients who could not be reached (retry period expired) [{"MSISDN":"44XXXXXXXX"},{"MSISDN":"39XXXXXXXX"},{"MSISDN":"356XXXXXXXX"}]
Example
                            
                                {
                                    "Ok": {
                                        "Awaiting": [
                                            {
                                                "MSISDN": "XXXXXXXXXXX"
                                            },
                                            {
                                                "MSISDN": "XXXXXXXXXXX"
                                            },
                                            {
                                                "MSISDN": "XXXXXXXXXXX"
                                            }
        
                                        ],
                                        "Delivered": [
                                            {
                                                "MSISDN": "XXXXXXXXXXX"
                                            },
                                            {
                                                "MSISDN": "XXXXXXXXXXX"
                                            },
                                            {
                                                "MSISDN": "XXXXXXXXXXX"
                                            }
                                        ],
                                        "Undelivered": [
                                            {
                                                "MSISDN": "XXXXXXXXXXX"
                                            },
                                            {
                                                "MSISDN": "XXXXXXXXXXX"
                                            },
                                            {
                                                "MSISDN": "XXXXXXXXXXX"
                                            }
                                        ],
                                        "Expired": [
                                            {
                                                "MSISDN": "XXXXXXXXXXX"
                                            },
                                            {
                                                "MSISDN": "XXXXXXXXXXX"
                                            },
                                            {
                                                "MSISDN": "XXXXXXXXXXX"
                                            }
                                        ]
                                    }
                                }
                            
                        

Push Method

Once you've registered for an account, you may then specify the callback URL that will be used to push delivery notifications in realtime to your application. Notifications will be in the form of POST requests (application/x-www-form-urlencoded), with the following request parameters:

Delivery notifications parameters

Field Type Description Notes
JobId GUID Respective job's unique identifier JobId=ce8c603b-c9cd-4908-8782-42e5be130fac
MSISDN String Recipient number MSISDN=44XXXXXXXX
Status String A string representing the delivery status for this specific recipient Status Codes to expect: "Delivered", "Undelivered", "Expired"

/Balance

(Top)

This GET method allows you to retrieve balance details for specific rates in your account.

Method

URI HTTP Method Authentication
https://targlets.com/api/Balance GET Username/Password or APIKey

Request Parameters

Parameter Type Description Required?
username String Email address with which you registered No
password String Password associated with the provided email address No
apikey GUID API Key generated after first login. You may retrieve this from the API and Defaults section of your dashboard. Click here to register for a free account. No
rateid GUID This is the specific rate for which you want to get balance details. You may have multiple rates and balances in your account depending on your messaging requirements (e.g. country specific). You will find the API key for each rate from the Balances and Alerts section. Yes

Response (Ok)

Response field Type Description Notes
RateId GUID A unique identifier for the required rate N/A
Balance Double The actual balance for the specified rate N/A

Example

                            
                                {
                                    "Ok": {
                                        "RateId": "62be8079-b370-42f8-a1e3-ebbd2c7d216d",
                                        "Balance": "50.00"
                                    }
                                }
                            
                        

Email Alerts

You may also specify alerts for the different rates from within the dashboard. Email notifications will be sent once the minimum threshold is reached. These thresholds may be specified from the Balances and Alerts section