API client to access Text Marketer's RESTful API, allows you to send SMS, check credits, create accounts, and more. Copyright © 2012 Text Marketer Ltd Client class to access Text Marketer RESTful API v1.2 Added sub-account creation function.
Use the sandbox system for testing. The sandbox will not modify your account in any way, but will respond normally to your requests.
Use the real production system.
Store the last xml string returned from the last RestClient call
Example:
RestClient rClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
rClient.getGroup("directors");
Console.WriteLine(rClient.Xml);
} catch (RestClientException e) {
Console.WriteLine(e.Message);
}
Constructor for the RestClient class.
username: your API Gateway Username
password: your API Gateway Password
env: possible values RestClient.ENV_SANDBOX or RestClient.ENV_PRODUCTION
Example:
RestClient tmClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
Make a call to TM Rest API Gateway to test if the username and password are correct.
Return Value: Boolean TRUE if login valid, FALSE if username or password not correct
Example:
RestClient rClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
if (rClient.isLoginValid())
Console.WriteLine("Login is OK!");
} catch (RestClientException e) {
Console.WriteLine(e.Message);
}
Get the number of credits currently available on your account.
Return Value: Integer with the credits currently available on your account.
Send a text message to the specified recipient.
message: The textual content of the message to be sent. Up to 612 characters from the GSM alphabet. The SMS characters we can support is documented at GSM character set. Please ensure that data is encoded in UTF-8.
mobile_number: The mobile number of the intended recipient, in international format, e.g. 447777123123. Only one number is allowed. To send a message to multiple recipients, you must call the API for each number.
originator: A string (up to 11 alpha-numeric characters) or the international mobile number (up to 16 digits) of the sender, to be displayed to the recipient, e.g. 447777123123 for a UK number.
validity: An integer from 1 to 72, indicating the number of hours during which the message is valid for delivery. Messages which cannot be delivered within the specified time will fail.
email: Optional. Available to txtUs Plus customers only. Specifies the email address for incoming responses. If you specify an email address, you must specify an originator that is a txtUs Plus number that is on your account, or you will get an error response.
custom: Optional. An alpha-numeric string, 1-20 characters long, which will be used to 'tag' your outgoing message and will appear in delivery reports, thus facilitating filtering of reports.
Return Value: Hash table with keys: message_id, credits_used and status
Example:
RestClient rClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
Hashtable result = tmClient.sendSMS("Hello SMS World!", "447777123123", "Hello World", 72, "", "");
Console.WriteLine("Used {0} Credits, ID:{1}, Status: {2}", result["credits_used"], result["message_id"], result["status"]);
} catch (RestClientException e) {
Console.WriteLine(e.Message);
}
Transfer credits from one account to another account, using the account number for the target.
quantity: The number of credits to transfer from the source account to the target account.
target: The account number of the account to transfer the credits to
Return Value: Hash table with keys: source_credits_before, source_credits_after, target_credits_before and target_credits_after
Example:
RestClient rClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
Hashtable result = rClient.transferCreditsToAccount(3, "902");
Console.WriteLine("Transfered 3 Credits (have {0} now), to account 902, now with {1} Credits", result["source_credits_after"], result["target_credits_after"]);
} catch (RestClientException e) {
Console.WriteLine(e.Message);
}
Transfer credits from one account to another account, using the account number for the target.
quantity: The number of credits to transfer from the source account to the target account.
target_username: The username of the account to transfer the credits to.
target_password: The password of the account to transfer the credits to.
Return Value: Hash table with keys: source_credits_before, source_credits_after, target_credits_before and target_credits_after
Example:
RestClient rClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
Hashtable result = rClient.transferCreditsToUser(3, "targetusername", "targetuserpass");
Console.WriteLine("Transfered 3 Credits (have {0} now), to account targetusername, now with {1} Credits", result["source_credits_after"], result["target_credits_after"]);
} catch (RestClientException e) {
Console.WriteLine(e.Message);
}
Get the availability of a given reply keyword. A reply keyword allows you receive incoming text messages to your account by providing people with a keyword, which they text to the short code 88802, e.g. text 'INFO' to 88802 to see this in action.
keyword: The keyword to check is availability.
Return Value: Hash table with keys: available and recycle.
Example:
RestClient rClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
Hashtable result = rClient.getKeyword("gold");
Console.WriteLine("The 'gold' keyword is available ({0}), recycled ({1})", result["available"], result["recycle"]);
} catch (RestClientException e) {
Console.WriteLine(e.Message);
}
Get a list of available 'send groups' - pre-defined groups containing a list of mobile numbers to send a message to. Also lists 'stop groups' - numbers in these groups will never be sent messages. Every account has at least one stop group, so that your recipients can always opt out of receiving messages from you. This is a legal requirement.
Return Value: Hash table array, each hash table with keys: id, numbers, name and is_stop.
Example:
RestClient rClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
Hashtable[] result = rClient.getGroups();
foreach (Hashtable group in result) {
Console.WriteLine("Group ID: {0}", group["id"]);
Console.WriteLine("Group numbers: {0}", group[""]);
Console.WriteLine("Group name: {0}", group["name"]);
Console.WriteLine("Group IS STOP: {0}", group["is_stop"]);
}
} catch (RestClientException e) {
Console.WriteLine(e.Message);
}
Get all the numbers in the group, if there are any.
group: Group name or group ID to get the numbers of
Return Value: array of String with the numbers of the group
Example:
RestClient rClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
Hashtable[] result = rClient.getGroup("directors");
foreach (String number in result)
Console.WriteLine("Number {0}", number);
} catch (RestClientException e) {
Console.WriteLine(e.Message);
}
Add a number/numbers to a 'send group' (excluding 'merge' groups).
group: group name or group ID to add the numbers to
numbers: numbers The MSISDN (mobile number) you wish to add, if you want to add more then one use a comma delimited list
Return Value: Return the number of added numbers to the selected group
Example:
RestClient rClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
int result = rClient.addNumbersToGroup("My Group", "447777000001,447777000002,44777700000");
Console.WriteLine("Added {0} numbers to My Group", result);
} catch (RestClientException e) {
Console.WriteLine(e.Message);
}
Create a new group.
group: the new Group name to be created
Return Value: eturn true if the group is added with success
Example:
RestClient rClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
if (rClient.addGroup("New Group"))
Console.WriteLine("'New Group' added with success.");
} catch (RestClientException e) {
Console.WriteLine(e.Message);
}
Retrieve a list of available delivery report names.
Return Value: String array with all the reports names
Example:
RestClient rClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
String[] result = rClient.getDeliveryReports();
foreach (String report in result)
Console.WriteLine("Report name: {0}", report);
} catch (RestClientException e) {
Console.WriteLine(e.Message);
}
Retrieve individual delivery report shows the current known status of all messages sent on a given day, or for a particular campaign. Whereas the function getDeliveryReports() gets a list of available delivery report names, including delivery reports for campaigns.
name: Name of the delivery report to retrieve or 'all' to retrieve all campaign/API report data
Return Value: DeliveryReport object array
Example:
RestClient rClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
DeliveryReport[] reports = rClient.getDeliveryReport("all");
foreach (DeliveryReport report in reports) {
Console.WriteLine(report);
foreach (Hashtable row in report.Rows) {
Console.WriteLine("\tMessage ID: {0}", row["message_id"]);
Console.WriteLine("\tLast Updated: {0}", row["last_updated"]);
Console.WriteLine("\tMobile Number: {0}", row["mobile_number"]);
Console.WriteLine("\tStatus: {0}", row["status"]);
Console.WriteLine("\tCustom {0}", row["custom"]);
}
} catch (RestClientException e) {
Console.WriteLine(e.Message);
}
Retrieve individual delivery report shows the current known status of all messages sent on a given day, or for a particular campaign. Whereas the function getDeliveryReports() gets a list of available delivery report names, including delivery reports for campaigns.
name: Name of the delivery report to retrieve or 'all' to retrieve all campaign/API report data
custom: Can specify a custom 'tag', which will restrict the search to those messages
Return Value: DeliveryReport object array
Example:
RestClient rClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
DeliveryReport[] reports = rClient.getDeliveryReport("all", "test");
foreach (DeliveryReport report in reports) {
Console.WriteLine(report);
foreach (Hashtable row in report.Rows) {
Console.WriteLine("\tMessage ID: {0}", row["message_id"]);
Console.WriteLine("\tLast Updated: {0}", row["last_updated"]);
Console.WriteLine("\tMobile Number: {0}", row["mobile_number"]);
Console.WriteLine("\tStatus: {0}", row["status"]);
Console.WriteLine("\tCustom {0}", row["custom"]);
}
} catch (RestClientException e) {
Console.WriteLine(e.Message);
}
Retrieve individual delivery report shows the current known status of all messages sent on a given day, or for a particular campaign. Whereas the function getDeliveryReports() gets a list of available delivery report names, including delivery reports for campaigns.
name: Name of the delivery report to retrieve or 'all' to retrieve all campaign/API report data
start: Get delivery report from start DateTime
end: Get delivery report to end DateTime
Return Value: DeliveryReport object array
Example:
RestClient rClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
DeliveryReport[] reports = rClient.getDeliveryReport("all", new DateTime(2012, 1, 1), DateTime.Today);
foreach (DeliveryReport report in reports) {
Console.WriteLine(report);
foreach (Hashtable row in report.Rows) {
Console.WriteLine("\tMessage ID: {0}", row["message_id"]);
Console.WriteLine("\tLast Updated: {0}", row["last_updated"]);
Console.WriteLine("\tMobile Number: {0}", row["mobile_number"]);
Console.WriteLine("\tStatus: {0}", row["status"]);
Console.WriteLine("\tCustom {0}", row["custom"]);
}
} catch (RestClientException e) {
Console.WriteLine(e.Message);
}
Retrieve individual delivery report shows the current known status of all messages sent on a given day, or for a particular campaign. Whereas the function getDeliveryReports() gets a list of available delivery report names, including delivery reports for campaigns.
name: Name of the delivery report to retrieve or 'all' to retrieve all campaign/API report data
custom: Can specify a custom 'tag', which will restrict the search to those messages
start: Get delivery report from start DateTime
end: Get delivery report to end DateTime
Return Value: DeliveryReport object array
Example:
RestClient rClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
DeliveryReport[] reports = rClient.getDeliveryReport("all", "test", new DateTime(2012, 1, 1), DateTime.Today);
foreach (DeliveryReport report in reports) {
Console.WriteLine(report);
foreach (Hashtable row in report.Rows) {
Console.WriteLine("\tMessage ID: {0}", row["message_id"]);
Console.WriteLine("\tLast Updated: {0}", row["last_updated"]);
Console.WriteLine("\tMobile Number: {0}", row["mobile_number"]);
Console.WriteLine("\tStatus: {0}", row["status"]);
Console.WriteLine("\tCustom {0}", row["custom"]);
}
} catch (RestClientException e) {
Console.WriteLine(e.Message);
}
Create a new account (requires additional permissions on your account, please contact Text Marketer to apply)
companyName: The company name for the new account owner
notificationMobile: (Optional*) the mobile number of the account (*required if $notificationEmail is not set)
notificationEmail: (Optional*) the email address of the account (*required if $notificationMobile is not set)
username: (Optional) the username you wish to set on the new account - the API username will be the same
password: (Optional) the password you wish to set on the new account - the API password will be the same
promoCode: (Optional) a promotional code entitling the account to extra credits
overrideRates: If set to true, use the credits rates set on your main account (the account used to access the API), rather than the Text Marketer defaults.
Return Value: Hash table with keys: account_id, company_name, create_date, credits, notification_email, notification_mobile, username, api_username and api_password
Example:
RestClient rClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
Hashtable result = rClient.createSubAccount("my subaccount", "44123456789", null, "subusername", "subpassword", null, false);
Console.WriteLine("Account ID: {0}", result["account_id"]);
Console.WriteLine("Company Name: {0}", result["company_name"]);
Console.WriteLine("Create Date: {0}", result["create_date"]);
Console.WriteLine("Credits: {0}", result["credits"]);
Console.WriteLine("Notification Email: {0}", result["notification_email"]);
Console.WriteLine("Notification Mobile: {0}", result["notification_mobile"]);
Console.WriteLine("Username: {0}", result["username"]);
Console.WriteLine("Password: {0}", result["password"]);
Console.WriteLine("API Username: {0}", result["api_username"]);
Console.WriteLine("API Password: {0}", result["api_password"]);
} catch (RestClientException e) {
Console.WriteLine(e.Message);
}
Return the last error code raised from the last RestClient call
Return Value: Error code integer or 0 if there is no error
Return the last error message raised from the last RestClient call
Return Value: Error message String or "" if there is no error
Return the all the errors raised from the last RestClient call
Return Value: Hashtable with all the errors codes and messages
Example:
RestClient rClient = new RestClient("myuser", "mypass", RestClient.ENV_SANDBOX);
try {
int credits = rClient.getCredits();
Console.WriteLine("Account have " + credits + " credits.");
} catch (RestClientException e) {
Console.WriteLine(e.Message);
foreach (DictionaryEntry de in rClient.getLastErrors())
Console.WriteLine("Error {0}: {1}", de.Key, de.Value);
}
Make the HTTP call to the REST API
service: e.g. credits, sms, group, etc..
method: HTTP method to use: PUT, GET, POST...
extraparams: Extra vars to add to the HTTP call
Return Value:
Parse Delivery Reports xml string and return a array of DeliveryReport Objects
xmlResp:
Return Value:
Initializes a new instance of the RestClientException class.
Initializes a new instance of the RestClientException class with the specified error message.
message: Error message
Initializes a new instance of the RestClientException class with the specified error message and nested exception.
message: Error message
inner: Nested exception
RestClientException
Initializes a new instance of the RestClientException class.
Initializes a new instance of the RestClientException class with the specified error message.
message: Error message
Initializes a new instance of the RestClientException class with the specified error message and nested exception.
message: Error message
inner: Nested exception
DeliveryReport Class represent a delivery report status from a sent SMS message
Delivery Report Name
Date of the last report update
Extension of the report file, e.g. csv
Return report rows for this Delivery Report
Constructor for the DeliveryReport class.
name: Report name
lastUpdate: Date of the last report update
extension: extension of the report file, e.g. csv
Add report row for this Delivery Report
last_updated: Date of the last row update
mobile_number: Report mobile number
message_id: Message unique identifier
status: Message status
custom: User custom tag
Convert deliveryReport to String
Return Value: String representing of DeliveryReport object