API

Integrate with our REST API.

Change history

  • 2014-02-28 Live
    • Added time to live for messages.
  • 2013-03-25
    • Limits and status codes change.
  • 2013-03-17
    • Added Source field.
  • 2013-03-14
    • Added Image support.
    • Mapping first link in mail message to Link field.
    • Attempted fix for parsing HTML only mail messages.
    • Removed custom mail headers.

Basics

Our API allows external message sources to send messages to Pushalot platform clients by using authorization tokens which are issued for each account on per app basis. By default every account has at least one authorization. This is for built in API app. When sending message your will need to specify at least authorization token and message body. After sending message our platform takes care of delivering it to all devices linked to account with given authorization token. Have in mind both IsImportant and IsSilent field flags may be overridden by user on per authorization basis.

Below is the table showing all possible incoming message fields.

Field Description
AuthorizationToken

String of 32 characters. Required

App authorization token which has to be obtained from the user, before being able to send any messages.

Title

String up to 250 characters.

Title for the message. Will show in client app in message listing in shortened version and in message detail in full version, so when possible try to keep most important information in the beginning of the text.

Body

String up to 32768 characters. Required

Body of the message. Will show in client app in message listing in shortened version and in message detail page in full version, so when possible try to keep most important information in the beginning of the text. Even though body field can store pretty big chunks of text, you should avoid it and rather link to external resource.

LinkTitle

String up to 100 characters.

Title for enclosed link in the Link field. Can only be specified if Link is specified.

Not supported by email gateway API.

Link

String up to 1000 characters.

Enclosed url link, has to be properly formatted in absolute URI form, that is with protocol, host etc.

Mapped from first URL link in email gateway API.

IsImportant

True or False.

Indicator whether the message should be visually marked as important within client app. Does not have any other implication on message delivery.

Mapped from mail high priority header in email gateway API.

IsSilent

True or False.

If set to True will prevent sending toast notifications to connected devices, resulting in silent delivery, as only badge icon will indicate new message.

Mapped from mail low priority header in email gateway API.

Image

String up to 250 characters.

Image thumbnail URL link, has to be properly formatted in absolute form with protocol etc. Recommended image size is 72x72 pixels. Larger images will be scaled down while maintaining aspect ratio. In order to save mobile device data plan, we download images from specified URL on server side and scale it there. This means client apps will never download big images directly by mistake.

Not supported by email gateway API.

Source

String up to 25 characters.

Notification source name that will be displayed instead of authorization token's app name.

Not supported by email gateway API.

TimeToLive

Integer number between 0 and 43200.

Time in minutes after which message automatically gets purged. Messages are checked for removal every 5 minutes.

In response to your request, our API will respond with adequate HTTP status code and JSON encoded result information. Below is the table of possible status codes.

Code Status Description
200 OK

The message has been sent successfully.

400 Bad request

Input data validation failed. Check result information Description field for detailed information.

405 Method not allowed

Method POST is required.

406 Not acceptable

Message throttle limit hit. Check result information Description field for information which limit was exceeded. See limits to learn more about what limits are enforced.

410 Gone

The AuthorizationToken is no longer valid and no more messages should be ever sent again using that token.

500 Internal server error

Something is broken. Please contact us so we can investigate.

503 Service unavailable

Our servers are currently overloaded with requests. Try again later.

Limits

To maintain high quality of service we need to enforce limits on communication with our platform. Below is table explaining limits that are in place. Have in mind those limits are subject to change.

Limit Description
Sending messages

Anonymous API calls are limited to 300 messages per 300 seconds per sender's remote address.

Account messages

There is a limit of 500 messages per account per day.

Unless deleted, messages are kept for 30 days from the moment they are received through the API. After that time they are automatically removed.

Device notifications

First message notification will be sent instantly to all devices, but subsequent notifications will be delayed till there is a span of 5 seconds without new notifications. This does not impact what you see within Pushalot client, only toast and tile push notifications.

For example if you receive 5 notifications each 3 seconds apart, only first and last one will be delivered to your device. First instantly and last after 17 seconds (4 messages * 3 seconds + 5 seconds).

REST API

Basic web API integration depends on uploading values encoded in application/x-www-form-urlencoded form with POST method to our API url located under address https://pushalot.com/api/sendmessage. This can be done using variety of software, or even using cURL command line tool.

Caution! If you are signed in, this page will use your own API authorization token in code examples below.

cURL

curl -F "AuthorizationToken=35b9832daffc4793aa477e44c0b0910f" \
	-F "Body=This is a test message body." \
	https://pushalot.com/api/sendmessage

C#

using (var client = new WebClient()) {
	var values = new NameValueCollection();
	values["AuthorizationToken"] = "35b9832daffc4793aa477e44c0b0910f";
	values["Body"] = "This is a test message body.";

	// client.Headers[HttpRequestHeader.ContentType] = "application/x-www-form-urlencoded";
	client.UploadValues("https://pushalot.com/api/sendmessage", values);
}

If one prefers to send values as JSON encoded, we also support this scenario. To make this happen set ContentType to application/json.

using (var client = new WebClient()) {
	var payload = JsonConvert.SerializeObject(new {
		AuthorizationToken = "35b9832daffc4793aa477e44c0b0910f",
		Body = "This is a test message body.",
	});

	client.Headers[HttpRequestHeader.ContentType] = "application/json";
	client.UploadString("https://pushalot.com/api/sendmessage", payload);
}

PHP

For PHP sibbl has an excellent API wrapper class Pushalot-PHP which is highly recommended or you can use curl module directly.

curl_setopt_array($ch = curl_init(), array(
	CURLOPT_URL => "https://pushalot.com/api/sendmessage",
	CURLOPT_POSTFIELDS => array(
		"AuthorizationToken" => "35b9832daffc4793aa477e44c0b0910f",
		"Body" => "This is a test message body.",
	)));
curl_exec($ch);
curl_close($ch);

Perl

use LWP::UserAgent;

LWP::UserAgent->new()->post("https://pushalot.com/api/sendmessage", [
	"AuthorizationToken" => "35b9832daffc4793aa477e44c0b0910f",
	"Body" => "This is a test message body.",
]);

Ruby

require "net/https"

url = URI.parse("https://pushalot.com/api/sendmessage")
req = Net::HTTP::Post.new(url.path)
req.set_form_data({
	:AuthorizationToken => "35b9832daffc4793aa477e44c0b0910f",
	:Body => "This is a test message body.",
})
res = Net::HTTP.new(url.host, url.port)
res.use_ssl = true
res.verify_mode = OpenSSL::SSL::VERIFY_PEER
res.start {|http| http.request(req) }

Email gateway

For scenarios where code integration is not possible, we provide email gateway. Its a mechanism that allows you to send normal email messages to specific address, that contains authorization token in it. Those messages are automatically picked up by our gateway and processed as if they arrived via normal web API. We auto map subject of the mail message to title and body to body. In case those mapped fields exceed maximum field length they are automatically truncated. If you specify mail priority as high, we treat that as if message was important and if you specify low priority, we treat it as silent message. We also extract first URL link in the mail body as the Link field.

using (var client = new SmtpClient("api.pushalot.com", 25)) {
	var message = new MailMessage();
	message.From = new MailAddress("youraddress@yourdomain.com");
	message.To.Add(new MailAddress("35b9832daffc4793aa477e44c0b0910f@api.pushalot.com"));
	message.Subject = "This goes into title";
	message.Body = "And this goes into message body.";
	message.Priority = MailPriority.High;

	client.Send(message);
}

This should work flawlessly for text based mail messages, but we still try to tweak our HTML email parsing capabilities. So be patient, as we work on improving gateway quality.