www.guerrillamail.com Open in urlscan Pro
178.162.170.166  Public Scan

Form analysis
0 forms found in the DOM

Text Content

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 support@guerrillamail.com


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:
    test@guerrillamailblock.com, 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, test@guerrillamailblock.com



 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.
    test@guerrillamailblock.com 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;

        }





}