Public API Documentation

Our public API is simple and easy to use.

These are the calls available:

URL HTTP Method Description
https://www.notifymyandroid.com/publicapi/verify GET Verifies if an API key is valid.
https://www.notifymyandroid.com/publicapi/notify POST Sends a notification.

Note that we strongly encourage the use of HTTPS on all your API calls, although you can fallback to HTTP in case you have no other choice.

When you call one of the APIs above, you will receive a xml formatted answer. You can find the details of a success and error messages below.

API Calls

/publicapi/verify

This call accepts a single API key as a parameter and returns if that key is valid or not.

Recommended HTTP Method: GET

All data submitted should be UTF-8 encoded.

Parameter Length (bytes) Description
apikey 48 The api key that you want to test if it is valid.
developerkey
(optional)
48 Your developer key, if you have one. This is optional.

Return codes:

Code Description
200 The 'apikey' supplied is valid.
400 The data supplied is in the wrong format, invalid length or null.
401 The 'apikey' provided is not valid.
402 Maximum number of API calls per hour exceeded.
500 Internal server error. Please contact our support if the problem persists.

Please see the return message format for more details.

/publicapi/notify

This call sends a notification. Note that you can pass an unlimited number of API keys on a single call.

Recommended HTTP Method: POST

All data submitted should be UTF-8 encoded. All fields are required, unless noted.

Parameter Length (bytes) Description
apikey unlimited API keys separated by commas. Each API key is a 48 bytes hexadecimal string.
When using multiple keys, you will only get a failure respose if all of them are not valid.
application 256(max) The name of the application that is generating the call.
Example: Nagios
event 1000(max) The event that is been notified. Depending on your application, it can be a subject or a brief description.
Example: Service is down!
description 10000(max) The notification text. Depending on your application, it can be a body of the message or a full description.
Example:
Server: 1.2.3.4
Service: mysqld
Status: DOWN
Time of the alert: 1/21/2011 1:32am
priority
(optional)
- A priority level for this notification. This is optional and in the future will be used to change the way NMA alerts you.
Possible values: -2, -1, 0, 1, 2
-2 = Very Low
-1 = Moderate
0 = Normal
1 = High
2 = Emergency
developerkey
(optional)
48 Your developer key, if you have one. This is optional.
url
(optional)
2000(max) An URL/URI can be attached to your notification. You can send URL's or URI's supported by your device. The user will be able to long-click the notification and choose to follow the attached URL/URI, launching the application that can handle it.
content-type
(optional)
Limited Options You can set this parameter to "text/html" while sending the notification, and the basic html tags below will be interpreted and rendered while displaying the notification:

  • <a href="...">, <b>, <big>, <blockquote>, <br>, <cite>
  • <dfn>, <div align="...">, <em>, <font size="..." color="..." face="...">
  • <h1>, <h2>, <h3>, <h4>, <h5>, <h6>
  • <i>, <p>, <small>, <strike>, <strong>
  • <sub>, <sup>, <tt>, <u>

Return codes:

Code Description
200 Notification submitted.
400 The data supplied is in the wrong format, invalid length or null.
401 None of the API keys provided were valid.
402 Maximum number of API calls per hour exceeded.
500 Internal server error. Please contact our support if the problem persists.

Please see the return message format for more details.

Return message format

Always use a XML parser. We should release changes and improvements over time that will change attributes and messages that may brake direct string parsers.

All messages will return a HTTP status code 200. That way you know when you were able to contact the server and the error is an application error or something else.

Error message

The error message contains an ERRORCODE and an ERRORMESSAGE. The ERRORMESSAGE is usually a more detailed message, like which parameter is invalid.

<?xml version="1.0" encoding="UTF-8"?>
<nma>
	<error code="ERRORCODE">ERRORMESSAGE</error>
</nma>

If the error is a 402 (API calls per hour limit exceeded) you will receive an extra attribute resettimer=TIMELEFT, which is a number that represents the minutes left before your limit per hour resets.

<?xml version="1.0" encoding="UTF-8"?>
<nma>
	<error code="402" resettimer="TIMELEFT">Your IP exceeded the maximum number of API calls per hour allowed.</error>
</nma>

Success message

The success message always contains a code 200 with two extra attributes: CALLSREMAINING and TIMELEFT. CALLSREMAINING is the number of API calls you have left before it resets. TIMELEFT is the number of minutes till the reset.

<?xml version="1.0" encoding="UTF-8"?>
<nma>
	<success code="200" remaining="CALLSREMAINING" resettimer="TIMELEFT" />
</nma>

Note that the 'remaining' attribute can return negative in case you are using a developer key that bypasses your hourly limit. We designed it that way so the developer can keep track if they are exceeding the usual quota.