Send Message API Page
Back to API Home

  1. API Specification
  2. Opt-In
  3. Sample Code
  4. Sample XML Responses
  5. Response Codes
API Specification

Send Message


The Send Message API function allows the developer to send an SMS text message to a user by specifying the mobile number and message text. The Send Message API function can be called via HTTP POST, which must contain the first five parameters specified below. The SMS text message is only sent to the intended mobile user if said user has opted in to receive SMS from developer. See the section on OPT-IN rules for more details. Successfully sent messages will result in the mobile user receiving a message containing up to 100 characters of developer specified message and 40 characters of an ad message appended to the end. If the message is marked as paid (developer must register payment at tagga.com to use paid flag), the user will receive a message containing up to 140 characters of developer specified message with no ad.

POST URL:
http://tagga.com/api/send/

POST Parameters:

  1. apikey - Developer API key, retrieve from API account at tagga.com
  2. passkey - Developer Password key, emailed to developer when API account approved
  3. tagg - Custom API tagg (keyword)
  4. mobile - Mobile number of intended message recipient, must be in full international format and only contain numeric characters
  5. message - Message content sent to recipient, must be between 0 and 100 characters for the latin character set, and 0 and 50 for all others. If message is paid, content can be between 0 and 140 characters for the latin character set, and 0 and 70 for all others.
  6. paid - Set to TRUE to send a sponsor-free text message, FALSE otherwise. Enables developer to send message containing up to 140 characters. Setting to TRUE requires that developer have valid payment (Optional). The price is $0.10 USD per message.

Restrictions:

  1. You can only send to users that have opted in. Users opt in by texting the developer's keyword to 82442 (+447624803802 for users outside of USA/Canada).
  2. You can only send a maximum of 1 message per user per hour (or configurable on a developer basis).å
  3. You can only send a maximum of 10,000 messages in a day (or configurable on a developer basis).
  4. If you attempt to send more than 5 messages to a mobile number that is not opted-in (return code of 1), tagga reserves the right to suspend your account. If you receive a response code of 1, it is your responsibility to mark the account as "opted-out".
  5. If a developer sends a message set as paid and does not have payment registered at tagga.com, developer will receive error code 18.

Response:
An XML response is returned and details a unique transaction ID, response code, and response message. You are responsible for checking the response message and acting appropriately.

Back to top
Opt-In

For a developer to be able to send to a user, the user must opt in to receive messages from the developer. To opt in to messages from a developer, the user must text the developer's keyword to 82442. This means that the developer will need to advertise this fact to the user (ex. Text TEAM to 82442 to get schedule updates). At the time of opt in, tagga will send the user a notification message letting them know that they have opted in. The message will also contain instructions on how to opt out. Users will be able to opt out by texting the developers keyword and then UNSUB (ex. Text TEAM UNSUB to unsubscribe from schedule updates).

Repeated Sends to an Opted Out User:
If an end user opts out and the developer attempts to send them an SMS, they will receive return code = 1 (Invalid Recipient - Not on allowed recipient list). The developer is responsible for deleting or marking the account in their database as 'opted out'. If tagga receives more than 5 requests for a user who has opted out, the developer account may be suspended.

Back to top
Sample Code

PHP


$postdata = http_build_query(
  array(
    'apikey' => 'abc123', // put your API key here
    'passkey' => '321cba', // put your API password key here
    'tagg' => 'sometagg', // the tagg you have reserved for this application
    'mobile' => '16045551234', // the user's mobile number
    'message' => 'This is the message I want to send to a subscribed user.'
  )
);

$opts = array(
  'http' => array(
    'method' => 'POST',
    'header' => 'Content-type: application/x-www-form-urlencoded',
    'content' => $postdata
  )
);

$context = stream_context_create($opts);
$response = file_get_contents(
  'http://tagga.com/api/send/',
  false,
  $context
);

// handle the response message


Python


import urllib

apikey = u'abc123' # put your API key here
passkey = u'321cba' # put your API password key here
tagg = u'sometagg' # the tagg you have reserved for this application
mobile = u'16045551234' # the user's mobile number
message = u'This is the message I want to send to a subscribed user.'

postdata = urllib.urlencode({'apikey': apikey, 'passkey': passkey, 'tagg': tagg, 'mobile': mobile, 'message': message})

response = urllib.urlopen('http://tagga.com/api/send/', postdata)

# handle the response message


Java


try {

  String postdata = URLEncoder.encode("apikey", "UTF-8") + "=" + URLEncoder.encode("abc123", "UTF-8");
  postdata += "&" + URLEncoder.encode("passkey", "UTF-8") + "=" + URLEncoder.encode("321cba", "UTF-8");
  postdata += "&" + URLEncoder.encode("tagg", "UTF-8") + "=" + URLEncoder.encode("sometagg", "UTF-8");
  postdata += "&" + URLEncoder.encode("mobile", "UTF-8") + "=" + URLEncoder.encode("16045551234", "UTF-8");
  postdata += "&" + URLEncoder.encode("message", "UTF-8") + "=" + URLEncoder.encode("This is the message I want to send to a subscribed user.", "UTF-8");

  // Send data
  URL url = new URL("http://tagga.com/api/send/");
  URLConnection conn = url.openConnection();
  conn.setDoOutput(true);
  OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());
  wr.write(postdata);
  wr.flush();

  // Get the response
  BufferedReader rd = new BufferedReader(new InputStreamReader(conn.getInputStream()));

  // handle the response here
  wr.close();
  rd.close();
} catch(Exception exc) {

  // handle any exceptions
}


Back to top
Sample XML Responses

Sample Success Response


<?xml version="1.0" encoding="UTF-8"?>
<TaggaResponse version="1.0">
  <TransactionID>100</TransactionID>
  <ReturnCode>0</ReturnCode>
  <Message>Success - API function call successful</Message>
</TaggaResponse>

Sample Error Response


<?xml version="1.0" encoding="UTF-8"?>
<TaggaResponse version="1.0">
  <TransactionID>101</TransactionID>
  <ReturnCode>10</ReturnCode>
  <Message>Send Frequency Exceeded - You have exceeded the send frequency for this user</Message>
</TaggaResponse>

Back to top
Response Codes
0: Success - API function call successful
1: Invalid Recipient - Not on allowed recipient list
2: Authentication Failed - apikey and passkey not valid
3: Incomplete API Call - Not all required parameters passed in
4: Invalid Mobile Number - mobile number was not in valid format
5: Message Length Invalid - Message text must be between 0 and 100 characters (140 if paid) for the latin character set, and 0 and 50 (70 if paid) for all others
6: Invalid Input - Some or all of the required parameters are invalid
7: Unknown Remote Address - This IP address is not allowed
8: Unknown tagg - Input tagg cannot be found
9: Send Limit Exceeded - You have exceeded the daily send limit
10: Send Frequency Exceeded - You have exceeded the send frequency for this user
18: No Valid Payment Found - Campaign not created or message not sent, no valid payment found

Back to top

  • Mobile Carrier Approved
    No Spam 100% Opt-In

  • Create SMS &
    Mobile Site Campaigns

  • Watch our video!

    Watch our short claytorial to learn more about tagga…

  • Tagga API

    Join our developer program and use the tagga API to create SMS applications.

  • The eye of the tagga blog

    Tagga CEO, Amielle Lake, Featured in DMNEWS Text messages more effective than mobile...