Guerrilla Mail JSON API

version 1.0, 19th Apr 2011

The latest version of this document is available on Google Docs here: https://docs.google.com/document/d/1Qw5KQP1j57BPTDmms5nspe-QAjNEsNg8cQHpAAycYNM/edit?hl=en

Introduction

Guerrilla Mail provides a JSON API through HTTP. The API is public and open to all.

The API URL is located at: http://api.guerrillamail.com/ajax.php

Each request to the above URL must have a parameter ‘f’, indicating the function name. It should also pass ‘ip’ and ‘agent’ to indicate the IP address and user-agent of the user-end. Followed by the argument(s) as required by the function specification. The result will be returned in a JSON encoded string.

Example:  http://api.guerrillamail.com/ajax.php?f=get_email_address&ip=127.0.0.1&agent=Mozilla_foo_bar

As a requirement, the client interacting with the API must be able to save, send and receive the following cookies

SUBSCR - A subscriber cookie. Set by the server if the email address has an active subscription. The client must save this value if changed, but does not need to send as a cookie at each request. (The value is later used as a parameter to a function call)

PHPSESSID - A session ID. Set by the server for each client to maintain state. The client must always look for this cookie in the HTTP header, remember it (if changed), and then provide it as cookie data in each HTTP request. This value can change at every call, and when it changes, it indicates that a new session was started; the client would need to re-fresh the interace with new data.

Note: The API may be rate limited, but we do not publish our rate limits. Please use this API carefully.

Created a guerrilla mail app? Let us know [email protected]

Flow

1. User accesses the Guerrilla Mail Application, an email address is given. App initialization, the mail box is loaded. (Call to get_email_address is made, the client can get the session id, email address and email address’ timestamp)

2. Check for new email, this could be a function that works in the background (A call to check_email is made)

3. New email arrives, the user clicks on it. Email is fetched and displayed (A call to fetch_email is made)

4. To change the email address - the user can set the email address.  (A call to set_email_user is made). After making a call to this function, the client can fetch the email list for this email by checking the email. Note: When a user changes the email address from one address to another, the old email address and its emails are NOT deleted, if the user changes back to the old address then their messages will still be there until the address expires or the message is 1 hour old.

5. Forget email - tell the server forget the current email address (but do not delete it) (A call to forget_me is made)

6. Extend time - Tell the server extend time for the current address (A call to extend is made)

7. Email expired - The client should keep time of when the email expires. Some calls also return a timestamp. The timestamp is a Unix timestamp, indicating when the address was created. The client can calculate how many minutes are remaining:

seconds remaining = 3600 - Current Timestamp - Email Timestamp

Note: A session can expire after about 18 minutes of inactivity. If a session expires, a new email address will be generated when making a call to get_email_address , a user can always return to the old email address by making a call to set_email_user

Functions

Each HTTP request to http://api.guerrillamail.com/ajax.php is considered a function call. The client could use GET when querying for data, and POST when setting or deleting data, although this is not strictly enforced. Each request must contain the ‘f’ parameter containing the function name, the ‘ip’ parameter of the end user, and the ‘agent’ parameter of the end user’s user agent.

Function

get_email_address

Arguments

  1. ‘lang’ - a string representing the language code. Currently supported: en, fr, nl, ru, tr, uk, ar, ko, jp, zh, zh-hant

  1. ‘SUBSCR’ - the subscriber cookie data, given to the client in a previous session

Description

The function is used to initialize a session and set the client with an email address. If the session already exists, then it will return the email address details of the existing session. If a new session needs to be created, then it will first check for the SUBSCR cookie to create a session for a subscribed address, otherwise it will create new email address randomly.

The session is maintained using HTTP Cookies. The cookie name is ‘PHPSESSID’, and it will be given in the resulting HTTP header. The client should always store this cookie and send it whenever making an API call. A new session will be created when the ‘PHPSESSID’ cookie is not given by the client. The function also generates a new welcome email for the user.

To send ‘PHPSESSID’ in a HTTP request, add the following line to the header:

Cookie: PHPSESSID=ABC1234\r\n";

Where ‘ABC1234’ is the data for the ‘PHPSESSID’ cookie.

The client should always watch the ‘PHPSESSID’ cookie for changes. If it changes, it needs to update this value, and pass it in subsequent calls.

Returns

An object with the following properties:

  1. ‘email_addr’ - The email address that that was determined. If a previous session was found, then it will be the email address of that session. If the SUBSCR cookie was matched, it will be the email in the cookie, otherwise a new random email address will be created.

  1. ‘email_timestamp’ - a UNIX timestamp when the email address was created. Used by the client to keep track of expiry.

  1. ‘s_active’ - Subscription active, Y or N
  2. ‘s_date’ - The full date of the subscription
  3. ‘s_time’ - The UNIX timestamp of subscription
  4. ‘s_time_expires’ - The UNIX timestamp for when the subscription expires

Note that the server could set a new SUBSCR cookie, also it may return with a new PHPSESSID cookie which you would need to update and store in your client.

Function

set_email_user

Arguments

  1. ‘email_user’ - String. The username part of an email address. example: [email protected], the email_user part would be ‘test’

  1. ‘lang’ - String. The language code, eg. ‘en’

Note: PHPSESSID must be passed as a cookie

Description

Set the email address to a different email address. If the email address is a subscriber, then return the subscription details. If the email is not a subscriber, then the email address will be given 60 minutes again. A new email address will be generated if the email address is not in the database and a welcome email message will be generated.

Returns

Similar to get_email_address, this function returns an object with the following properties:

  1. ‘email_addr’ - The email address that that was determined. If a previous session was found, then it will be the email address of that session. If the SUBSCR cookie was matched, it will be the email in the cookie, otherwise a new random email address will be created. Eg, [email protected]

  1. ‘email_timestamp’ - a UNIX timestamp when the email address was created. Used by the client to keep track of expiry.

  1. ‘s_active’ - Subscription active, Y or N
  2. ‘s_date’ - The full date of the subscription
  3. ‘s_time’ - The UNIX timestamp of subscription
  4. ‘s_time_expires’ - The UNIX timestamp for when the subscription expires

Function

check_email

Arguments

  1. seq - The sequence number (id) of the oldest email
Description

Check for new email on the server. Returns a list of the newest messages. The maximum size of the list is 20 items.

The client should not check email too many times as to not overload the server. Do not check if the email expired, the email checking routing should pause if the email expired.

Returns

An an object with the following properties:

  1. ‘list’ - A list of messages, represented as an array of objects. Each object has the following properties:
            ‘mail_id’,

‘mail_from’ (email address of sender),

‘mail_subject’,

‘mail_excerpt’ (snippet from the email),

‘mail_timestamp’ (a UNIX timestamp),

‘mail_read’ (1 if read, 0 if not), ‘mail_date’

Note: ‘mail_subject’ and ‘mail_excerpt’ are escaped using HTML Entities.

  1. ‘count’ - The number of emails matched. This can be much more than the maximum that can be returned (20)! This number indicates the total number of new emails in the database. (If you want to get the emails after the first 20, then make another call with the get_older_list function
  1. ‘email’ - The email address which the list is for. Eg. [email protected] The client would need to watch this variable to detect any changes to sync the address.
  2. ‘ts’ - The timestamp of the email address, time of when the email address was created. The client can use this variable to sync the time. Emails expire after 60 minutes
  3. ‘s_active’ - Subscription active, Y or N
  4. ‘s_date’ - The full date of the subscription
  5. ‘s_time’ - The UNIX timestamp of subscription
  6. ‘s_time_expires’ - The UNIX timestamp for when the subscription expires

Function

get_email_list

Arguments

  1. ‘offset’ - How many emails to start from (skip). Starts from 0

  1. ‘seq’ - The sequence number(id) of the first email, optional

Description

Gets a maximum of 20 messages from the specified offset. Offset of 0 will fetch a list of the first 10 emails, offset of 10 will fetch a list of the next 10, and so on.

This function is useful for populating the initial email list. Note: When returned, subject and email excerpt are escaped using HTML Entities.

Returns

Identical to check_email described above

Function

fetch_email

Arguments

  1. email_id - The id of the email to fetch

Description

Get the contents of an email.

Notes:

- All HTML in the body of the email is filtered. Eg, Javascript, applets, iframes, etc is removed.

- All images in the email are relative to http://www.guerrillamail.com/res.php - this script will generate a ‘blocked by GM’ image, indicating that the image was blocked. The CGI parameters for this script are as follows:

        r = Is it a resource? 1 if true. Always 1

        n= Node. The element type. Can be a string of letters (a-z)

        q= The query string for the original image. This is URL Encoded

        Example URL: http://www.guerrillamail.com/res.php?r=1&n=img&q=http%3A%2F%2Fstatic.groupon.de%2Fnewsletter_ums%2Flogo_groupon_de_DE.gif

        When an email is displayed by the client, it should displayed the blocked images generated by res.php. When a ‘Display Images’ button is clicked, the client should use a regular expression to replace the links to res.php with the links to the image found in the ‘q’ parameter. Here is an example of this regular expression in the Javascript client:

// Javascript example: This will replace all the res.php links inside double quotes with the URL stored in the q parameter. Since the URL in the q parameter is URL Escaped, we need to define an anonymous function to unescape the matched parameter. The ‘g’ flag tells the regex engine to replace all occurrences in the string.

temp_html = temp_html.replace(/"\/res\.php\?r=1&n=[a-z]+&q=([^"^&]+)"/g, function(str, p1, offset, s) {return unescape (p1); } );

      // Sometimes the link can be enclosed inside html encoded quotes, "

temp_html = temp_html.replace(/"\/res\.php\?r=1&n=[a-z]+&q=([^"]+)"/g, function(str, p1, offset, s) {return """+unescape(p1)+""" ; } );

Here is the above example written as PHP code (using the ‘e’ modifier allows us to call the urldecode function on the matched parameter):

$source = preg_replace ('#"/res\.php\?r=1&n=img&q=([^"]+)"#e', "urldecode('\\1')", $source);

$source = preg_replace ('#"/res\.php\?r=1&n=img&q=([^"]+)"#e', "urldecode('\\1')", $source);

- Subject and email excerpt are escaped using HTML Entities.

- Only emails owned by the current session id can be fetched.

Function

forget_me

Arguments
  1. email_addr
Description

Forget the current email address. This will not stop the session, the existing session will be maintained. A subsequent call to get_email_address will fetch a new email address or the client can call set_email_user to set a new address. Typically, a user would want to set a new address manually after clicking the ‘forget me’ button.

Returns

True if successful. Note that the SUBSCR cookie will be deleted after making this call, however, PHPSESSID will persist.

Function

del_email

Arguments
  1. email_ids - array or an integer, in the following format: email_ids[]=425&email_ids[]=426&email_ids[]=427

    Where 425, 426 and 427 are the ids of emails to delete. In a HTTP request, this parameter would be encoded like this:

email_ids%5B%5D=425&email_ids%5B%5D=426&email_ids%5B%5D=427

(See example PHP code below for how the $req string is generated. Another example here http://snipplr.com/view/4444/passing-an-array-through-get-request/)

Description

Delete the emails from the server

        Returns

An array of deleted email ids

Function

extend

Arguments
  1. (none)

Description
Extend the email address time by 1 hour. A maximum of 2 hours can be extended.
Returns

An object with the following properties:

‘expired’ - true or false, indicating if the email has expired

‘email_timestamp’ - A UNIX timestamp indicating the time of when the address was created. Can be in the future.

‘affected’ - 1 if extended successfully, 0 if not successful

Sample client code (PHP):

The following sample code shows how to interact with the API using PHP:

require('JSON.php'); // grab your copy from http://mike.teczno.com/json.html or change the code to use the JSON PHP extension if you have it enabled.

function api_call($function, $params, $req_type='POST', $decode=true) {

        $params['ip'] = $_SERVER['REMOTE_ADDR'];

        $params['agent'] = substr($_SERVER['HTTP_USER_AGENT'], 0, 160);

        $result = null;

   

 

   

   if (isset($_COOKIE['SUBSCR'])) {

       $toks = explode(':', $_REQUEST['SUBSCR']);

       $hash = array_shift($toks);

       $email_addr = array_shift($toks);

       $email_timestamp = array_shift($toks);

               

       $params['SUBSCR'] = $_COOKIE['SUBSCR'];

       

   }

        $req = 'f='.$function;

        foreach ($params as $key => $val) {

       if (is_array($val)) {

           foreach ($val as $ak => $av) {

               $req .= '&'.$key.'%5B%5D='.urlencode($av);

           }

       } else {

           $req .= '&'.$key.'='.urlencode($val);

       }

        }

   

        

        $host = 'www.guerrillamail.com';

   

   if (strpos(__FILE__, '/dev')!==false) {

       $resource = '/dev/ajax.php';

   } else {

           $resource = '/ajax.php';

   }

//echo '<A href="http://'.$host.$resource.'?'.htmlentities($req).'">'.htmlentities($host.$resource).'?'.htmlentities($req).'</a>';

        $fp = fsockopen ($host, 80, $errno, $errstr, 10);

        

        

        if ($fp) {

        

                if ($req_type=='GET') {

                        $get = $resource.'?'.$req;

                        $send  = "GET $get HTTP/1.0\r\n"; // dont need chunked so use HTTP/1.0

                        $send .= "Host: $host\r\n";

                        $send .= "User-Agent: Guerrilla Mail API (www.guerrillamail.com)\r\n";

                        $send .= "Referer: ".$_SERVER['SERVER_NAME']."\r\n";

                        if (isset($_SESSION['API_SESSION'])) {

                                //$send .= "Cookie: PHPSESSID=".$_SESSION['API_SESSION']."\r\n";

               

                        }

           $send .= "Cookie: PHPSESSID=".session_id()."\r\n";

           

                        $send .= "Content-Type: text/xml\r\n";

                        $send .= "Connection: Close\r\n\r\n";

                } else {

                        // Post the data

                        $send = "POST ".$resource." HTTP/1.0\r\n";

                        $send .= "Host: $host\r\n";

                        $send .= "User-Agent: Guerrilla Mail API (www.guerrillamail.com)\r\n";

                        $send .= "Referer: ".$_SERVER['SERVER_NAME']."\r\n";

                        if (isset($_SESSION['API_SESSION'])) {

                                //$send .= "Cookie: PHPSESSID=".$_SESSION['API_SESSION']."\r\n";

                        }

           $send .= "Cookie: PHPSESSID=".session_id()."\r\n";

           

                        $send .= "Content-Type: application/x-www-form-urlencoded\r\n";

                        $send .= "Content-Length: " . strlen($req) . "\r\n\r\n";

                        $send .= $req; // post the request

                }

       

       //echo $send;

                if ($sent = fputs ($fp, $send, strlen($send)))  {  // do the request

                        // skip headers... parse cookies

                        while (!feof($fp)) { // skip the header

                                $res = fgets ($fp);

                                if (preg_match ('#Set-Cookie: PHPSESSID=(.+?);#', $res, $m)) {

                                        // extracted the PHP session ID

                                        // so that we can maintain a session between the client/server

                                        $_SESSION['API_SESSION'] = $m[1];

                                }

               

               // grab the SUBSCR cookie from the reply and set to the client

                                if (preg_match ('#Set-Cookie: (SUBSCR=.+)#', $res, $m)) {

                                        $data = explode(';', $m[1]);

                                        foreach ($data as $item) {

                                                $pair = explode('=', $item);

                                                if (trim($pair[0])=='expires') {

                                                        // needs to be in a unix timestamp

                                                        $cookie[trim($pair[0])] = strtotime(trim(urldecode($pair[1])));

                                                } else {

                                                        $cookie[trim($pair[0])] = trim(urldecode($pair[1]));

                                                }

                                        }

                                        if ($_SERVER['HTTP_HOST']=='localhost') {

                                                $host = $_SERVER['HTTP_HOST'];

                                        } else {

                                                $host = '.'.str_replace('.www', '', $_SERVER['HTTP_HOST']);

                                        }

                                        if (setcookie('SUBSCR', $cookie['SUBSCR'], $cookie['expires'], '/', $host)) { // , $host

                                                //echo 'cookie set';

                                        }

                                }

                

                                if (strcmp($res, "\r\n")===0) break;

                        }

                }

        

                $buffer = '';

                if ($sent) {                         

                        while(!feof($fp)) {

                                $buffer .= fread($fp, 1024);        

                        }

                        $JSON = new Services_JSON();

                        if ($decode) {

                                $result = $JSON->decode($buffer);

                        } else {

                                $result = $buffer;

                        }

                                                

                }

                if ($fp) {

                        fclose($fp);

                }

                return $result;

        } else {

                return null;

        }

}