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
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
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
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.
get_email_address
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.
An object with the following properties:
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.
set_email_user
Note: PHPSESSID must be passed as a cookie
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.
Similar to get_email_address, this function returns an object with the following properties:
check_email
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.
An an object with the following properties:
‘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.
get_email_list
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.
Identical to check_email described above
fetch_email
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.
forget_me
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.
True if successful. Note that the SUBSCR cookie will be deleted after making this call, however, PHPSESSID will persist.
del_email
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/)
Delete the emails from the server
An array of deleted email ids
extend
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
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;
}
}
