CriSend API

Introduction to CritSend's API

Download connectors: .Net Java PHP(connector) PHP(example) Ruby gem: MxmConnect

To use CritSend, you can either choose our enhanced SMTP gateway or our HTTP API.

Our SMTP gateway is easier to use if you have an already existing system in place. Our API is better if you want a tighter integration and wish to enjoy our additional features. It offers more features but is a little bit harder to integrate with an existing system. We recommend to use our API if you build a new delivery service.

**Comparison Summary of API vs enhanced SMTP**
	High Volume Performance	Ease of integration	Delivery Latency	Enhanced Features
API	++		+++	++++
SMTP		++++

This document assumes that your CritSend account is active and configured (including SPF, DomainKey,...).
In italics are the changes planned for the next version which will be released in a few weeks.

Enhanced SMTP Gateway

See http://www.critsend.com/smtp-service-setup

Suppression List Management

We manage this for you at the address level: unsubscription, image display (who clicked on display image), permanent failures, bounces and spam report (user clicking on the « report spam » button on a selection of ISPs). Optionally, we can handle click throughs.

We store a unique identifier of invalid emails and manage for you bounce, spam report and unsubscription. You don't need to process them: we store them and suppress them from your deliveries for you. You can export them through our back-office and edit them if necessary. These lists are always accessible through our API in real time.

API

CritSend's powerful API allows you to reliably send mails, and access customized reports providing in-depth knowledge and alerts on your deliveries and recipient behaviors.

We provide our users with a connector (a helper library) in all major language. If your language of choice is not covered let us know we will port our connector to this language and support it.

Currently we support: PHP, Java, Ruby and .NET. All the connectors are open source and are released as such.

With each version of the API, we try to maintain backward compatibility. If we do not, we will have a six months delay during which both versions are active.

Real-Time Reporting
Advanced Email Tagging

1. Tag Concept

A tag is an ascii alpha-numerical string under 40 characters. The dash (-) character is allowed.

One or several tags are attached to a delivery. Each time you tag an email you signal the service to add it to a reporting with the name of the tag. Reporting contains all the information we have collected about the deliveries with this tag (see below for the list). Tags are also shown in the Analytics section of our website. For instance, if you use CritSend to reliably send invoices, password reminders and newsletters each type of delivery should be tagged.
tag:'invoice1' or tag:'forgot-password' or tag:'june-newsletter'
where tag is an alphanumerical ascii string (can contain dashes) under 40 characters. If you don't attach a tag to your deliveries, CritSend will create a tag named default.

If using the enhanced SMTP gateway, tags can be passed using the X-tags: header.

2. Real-Time Reporting

Real-time reporting is an XML feed containing the following information for each email address:

image display
spam report
unsubscribe
bounce (temporary error; we retry automatically)
permanent failure
click (if the module is activated)
delivery OK (if the module is activated)

Optionally we can pass you back a unique identifier you have passed us.

Creation of a tag is implicit. Once created a tag can never be safely removed. We can receive events even months after its creation (e.g. Some end-users always open their registration email to go on the website)

To work with the tags with the API, you can use the following functions:

boolean deleteTag(String tag) deletes the named tag. True if success; False otherwise. Ex: deleteTag('your-tag')
String getTag(String tag) get the content of the tag. Sends you back an XML file. This function will send you back the whole datasets. It is unappropriate for large datasets.
String getTagPaginated(tag, start, offset) get the content of the tag between lines start and start + offset. The resulting file is always a well formed XML file. Start is the line you start with and offset the number of lines you want.
Ex: getTagPaginated('your-tag', 0, 200)
0 is the start line, 200 number of lines you want
String[] listAllTags() gives you an array with all your tags.
String getIntersection(String[] tag) gives you reports that are present on all tags in the array.
String getIntersectionPaginated(String[] tag) same as getIntersection but paginated.

Reporting Data Format

Each tag file is enclosed into a <reporting version=''1'' tag=''''> tag is an attribute containing the name of the tag.

Each report information is containted in a status or an action tag. The tag is contained in a report tag containing the address. For instance:

A line can be repeated several times, this means we have retried delivering the email and get this error again. In this case we first bounced the address and then send back a permanent failure.

Status

Status contains all information that will change your user status. This tag is of the following form:

<status time="2008-06-10T14:35:33Z">value</status>

time contains a timestamp in the DateTime XML schema format.

Value can have the values below:

unsubscribed	User has unsubscribed
Spam report	User has clicked on Spam report
Bounced	User's email has bounced (soft bounce)
Permanent failure	User's email is invalid
Unsent	We have filtered the email

Action

Action represents an information about your user.

value is an optional attribute.

click	User has clicked the link in URL
open	User has rendered the email

Example of the XML file accessible through getTag

This is an example file. Namespaces are omitted for clarity of purposes. The example below contains all the values we currently support. Please note, "open" means the image display and is activated on demand.

<reporting version=''1'' tag=''invoice''>
<report address="bxb@live.fr"> <status time="2008-06-10T14:35:47Z">Permanent failure</status></report>
<report address="bxb@live.fr"> <status time="2008-06-10T14:35:47Z">Permanent failure</status></report>
<report address="ntoper@gmail.com"><status time="2008-06-10T14:35:33Z">Spam
report</status></report>
<report address="hello@live.fr"><status
time="2008-06-10T14:35:47Z">Bounced</status></report>
<report address="hello@live.fr"><status
time="2008-06-10T14:35:47Z">Permanent failure</status></report>
<report address="yothere@yahoo.fr"><status
time="2008-06-10T14:35:47Z">unsubscribed</status></report>
</reporting>

3. Advanced Email Delivery

Our API is used for high volume deliveries. They need a high throughput. The combination of template engine and some HTTP parameters allow volume. We use pipelined, compression if needed and can send several unique emails through the same connection. The API is REST-based.

Fault tolerance is embedded in the connector. When an error is thrown the connector retries automatically on other server of the cluster.

You can pass to each email not only an email but also a unique ID.

the delivery parameters (mail from, friendly mail from, reply-to)
the content of the delivery (subject, html, text, attachment)
the actual email address(es) and optionally their template parameters. Up to 500 addresses per request.

Specific configuration is language specific. An example program or script is bundled with every connector.

Example of Sending API mail in PHP

$content = array('subject'=> 'My subject', 'html'=> 'my html' , 'text' =>'my test');

$param = array('tag'=>array('invoice1'), 'mailfrom'=> 'ntoper@critsend.com', 'mailfrom_friendly'=> 'Nicolas Toper', 'replyto'=>'ntoper@critsend.com', 'replyto_filtered'=> 'true');

$emails[0] = array('email'=>'happy@customer.com', 'field1'=> 'test');

//}
   try {
   echo $j;
   print_r($mxm->sendCampaign($content, $param, $emails));
} catch (MxmException $e) {
echo $e->getMessage();
}

4. Template Engine

If you send a bulk email with mostly the same parameters, you can offload the email generation to CritSend.

CritSend replaces all occurrences of <mxm var="*" />

* can hold the following values: field1, field2, field3,..., field15, mirror and unsub. * can hold any values.

field1, 2, 3,..., 15 are described in the email component of the delivery. If the value is not present in the email component, it will be evaluated to an empty string. If the value is not mirror or unsub, it should be in the email component of the query.

mirror is a special value to holds a mirror page. A mirror page is a link to a webpage with the content of the email. It is useful with old email client or complicated HTML email that can have issue rendering properly the email. Our analysis shows that 5% of the recipients will click on that link.

Unsub is the unsubscription link. We redirect to a specific page of your choice passing as parameters the tag and the email address of the unsubscription.

Both domains (for mirror and unsub) can be customized to your own.

Incoming emails

CritSend can handle incoming emails. In this case, we filter virus, spam and bounces for you Incoming emails can be sent back to you on two formats.

Email are useful to redirect « human answers » to your customer care. Some end-users reply to automated email and they are usually important emails to handles. We can redirect to specific addresses depending on some filters (e.g. Specific word)
JSON RPC we handle for you encoding and attachment processing and send you an HTTP request. Emails encoding are hard and contain a lot of edgy cases.

If you want to activate incoming emails,

Contact CritSend so we can activate this feature for you with the domain name and the URL or email address where to redirect.
Add our MX in your DNS. (add an mx to smtp.critsend.com)

JSON Data Format

All strings are json encoded (meaning part UTF8, part ascii). You should return a 200 HTTP code if things are correct.

If your server is unreachable or if you send us something else than a 200 HTTP code, we will log the message on our side for manual replay.

Data format is the following:

(Please note: yes, attachement is spelled attachement in the descriptor, this is not a typo)

{ 'message': {<all data about the messages>} 'attachements: [<all attachement>] }

<messages> = {'to': recipient, 'mailfrom': mailfrom ,'subject': subject, 'html': html, 'text':text}

<attachement> (I describe only one; they are stored in a list to handle as many attachment as you want):

{'maintype': <text>|<image>| etc, 'subtype':<plain>|<jpeg>|etc., 'filename': (if we have it), 'data': <base64 encoded of the data>}a