Page 1 of 1

API References 1.0

Posted: 22 Nov 2007, 23:33
by Admin
TrashMail References API Version 1.0

This is the first version of an official API documentation to write tools to use the TrashMail service.
Note: This document has been written in this forum so that it can be also discussed by the TrashMail forum users.

Goal: TrashMail provides a simple Web API that programs could be written in an easy way to use the TrashMail service.

Creating a TrashMail address
To create a TrashMail address a HTTPS POST request must be made to the following URL with the following parameters.

URL:

Code: Select all

https://ssl.trashmail.net/?
Parameters:
  • form_source: TrashMail user name to use. Its usually a random name with 8 caracters.

    form_dest: Destination email address.

    form_nb_redirections:
    Number of redirections

    form_expire_days: How many days this account should be valid

    form_whitelisting: Enable or disable whitelisting. 0 = Disable Whitelisting, 1 = Disable Confirmation, 2 = Confirmation for every message, 3 = Confirmation + Whitelisting

    delete_msg_chk: 0 = don't notify me when the account has been deleted, 1 = notify when it has been deleted

    ext_url (optional): optional URL address parameter, when passed, then TrashMail server will store this URL. The Mozilla FireFox Add-On uses this that TrashMail members can remember where they created their email addresses. It will be soon displayed on the modification page and can not be modified once the TrashMail account has been created.

    create_submit: "Create disposable email address" = should be passed, that the server things the form create button has been pressed. Theoretically any value could be passed, but this parameter must be set.

    API: 1 = API has been used to create TrashMail account. 0 = API is not used. When the API is used, then TrashMail will only respond only in simple text mode without any kind of HTML tags. This should be easier for tools to parse the response.
Return values
One of the following two lines could be returned:
1. On success:

Code: Select all

STATUS=OK DEA=$my_source DN=$my_domainname REAL=$my_form_dest DAYS=$my_days NB_FORWARDS=$my_nb_forwards DELETE_LINK=$delete_link"
Return arguments:
$my_source: source name to confirm
$my_domainname: source domain name
$my_form_dest: destination email address
$my_days: days how long the account will be valid
$my_nb_forwards: how many forwards could be done with the account
$delete_link: URL link on which the account could be directly deleted

2. On error:

Code: Select all

STATUS=ERR MSG=|Error message|
Example of a POST request in Javascript:

Code: Select all

  req = new XMLHttpRequest();
  try
    {
      req.open('POST', 'https://ssl.trashmail.net/?', false);
      req.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');

      var current_url = main_window.content.document.location.toString();
      var str_ext_url = "&ext_url=" + encodeURIComponent(current_url);
 
      req.send("form_source=" + encodeURIComponent(fwd_name.value) + "&form_dest="
               + encodeURIComponent(real_addr.value) + "&form_nb_redirections=" + encodeURIComponent(fwd_menu.value)
               + "&form_expire_days=" + encodeURIComponent(ls_menu.value)
               + "&form_whitelisting=" + encodeURIComponent(challenge_response.value)
               + "&delete_msg_chk=" + encodeURIComponent((notify.checked == true) ? "1" : "0")
               + str_ext_url
               + "&create_submit=" + encodeURIComponent("Create disposable email address")
               + "&API=1"); /* set API to 1, to tell TrashMail.net, this is an API call */
   }
  catch (e)
    {
      alert(e);
      exit;
    }
The TrashMail.net Mozilla Firefox Add-On is open source and could be used as example. Simply download on mozilla.com the .xpi file and rename it as .zip file then open it with an unzip program.

Comments:
Note that the HTTPS (HTTP over SSL) protocol must be used. The TrashMail web server refuses to create email addresses on the HTTP plain text mode to protect the privacy of the users.
Note also that the URL parameters must be encoded in URI format. I.e. in Javascript there is the function encodeURIComponent(var string) which does it.

Get realtime stats
The realtime stats have been recently added. Any tool could also get the realtime stats (refreshed every 5 seconds) by doing a HTTP or HTTPS GET request on

Code: Select all

http://www.trashmail.net/?cmd=show_stats
or

Code: Select all

https://ssl.trashmail.net/?cmd=show_stats
.
The response is a line in text mode answer in the following format:
total_spam_mails:spam_mails_per_second
Example: 9609228:0.60
Which means that a total of 9609228 spam mails have been blocked and 0.60 spam mails per second as average (refreshed every 5 seconds) has been blocked.

API comments:
At any time this API could be discussed, improoved, changed etc. Simply write your comments or questions in this forum that everybody could share the different opinions.

Re: API References 1.0

Posted: 27 Jun 2009, 18:37
by missinglink
PHP Class

Code: Select all

<?php
/**
 * Trashmail API ver 1 PHP Class
 * Used to create a new Trashmail address
 * 
 ._  _ _|_ _ ._   o _ |_ ._  _ _ ._ 
 |_)(/_ |_(/_|    |(_)| || |_>(_)| |
 |               _|                 

 * Peter Johnson
 * @email [email protected]

 * Sample Response:
	Array
	(
		[STATUS] => OK
		[DEA] => new-alias
		[DN] => trashmail.net
		[REAL] => [email protected]
		[DAYS] => 30
		[NB_FORWARDS] => 10
		[DELETE_LINK] => https://ssl.trashmail.net/?cmd
	)
	or FALSE on error
	
* Usage:
	$tm = new Trashmail( "new-alias", "rcpt.at", "[email protected]" );
	$return = $tm->query();
	
	echo "<pre>"; print_r( $return ); echo "</pre>";
**/
		
final class Trashmail
{
	private $url = "https://ssl.trashmail.net/?API=1";
	private $data = array(
		"form_nb_redirections"	=> "10",
		"form_expire_days"		=> "30",
		"form_whitelisting"		=> "0",
		"delete_msg_chk"		=> "1",
		"create_submit"			=> "Create%20disposable%20email%20address",
		"API"					=> "1",
	);

	final public function setData( $id, $val ){ $this->data[ $id ] = $val; }

	final public function __construct( $new_email_alias, $new_domain, $forward_to )
	{
		$this->setData( 'form_source'	, $new_email_alias );
		$this->setData( 'form_domain'	, $new_domain );
		$this->setData( 'form_dest'		, $forward_to );
	}
	
	final public function query()
	{
		$ch = curl_init ( $this->url );
		curl_setopt( $ch,	CURLOPT_RETURNTRANSFER	, true );
		curl_setopt( $ch,	CURLOPT_USERAGENT		, 'Opera/9.23 (Windows NT 5.1; U; en)' );
		curl_setopt( $ch,	CURLOPT_HTTPAUTH		, CURLAUTH_ANY );
		curl_setopt( $ch,	CURLOPT_SSL_VERIFYPEER	, false );
		curl_setopt( $ch,	CURLOPT_SSL_VERIFYHOST	, 2 );
		curl_setopt( $ch,	CURLOPT_POST			, 1 );
		curl_setopt( $ch,	CURLOPT_POSTFIELDS		, $this->data );
		
		return $this->formatResult( curl_exec( $ch ) );
	}
	
	final private function formatResult( $result )
	{
		$return = array();
		
		foreach( split( ' ', $result ) as $spl )
		{
			$data_split = split( '=', $spl );
			$return[ $data_split[0] ] = $data_split[1];
		}
		
		return ( $return['STATUS'] == 'OK' ) ? $return : false;
	}
}
?>

Re: API References 1.0

Posted: 27 Jun 2009, 19:03
by Admin
missinglink wrote:PHP Class

Code: Select all

<?php
/**
 * Trashmail API ver 1 PHP Class
 * Used to create a new Trashmail address
 * 
 ._  _ _|_ _ ._   o _ |_ ._  _ _ ._ 
 |_)(/_ |_(/_|    |(_)| || |_>(_)| |
 |               _|                 

 * Peter Johnson
 * @email [email protected]

 * Sample Response:
	Array
	(
		[STATUS] => OK
		[DEA] => new-alias
		[DN] => trashmail.net
		[REAL] => [email protected]
		[DAYS] => 30
		[NB_FORWARDS] => 10
		[DELETE_LINK] => https://ssl.trashmail.net/?cmd
	)
	or FALSE on error
	
* Usage:
	$tm = new Trashmail( "new-alias", "rcpt.at", "[email protected]" );
	$return = $tm->query();
	
	echo "<pre>"; print_r( $return ); echo "</pre>";
**/
		
final class Trashmail
{
	private $url = "https://ssl.trashmail.net/?API=1";
	private $data = array(
		"form_nb_redirections"	=> "10",
		"form_expire_days"		=> "30",
		"form_whitelisting"		=> "0",
		"delete_msg_chk"		=> "1",
		"create_submit"			=> "Create%20disposable%20email%20address",
		"API"					=> "1",
	);

	final public function setData( $id, $val ){ $this->data[ $id ] = $val; }

	final public function __construct( $new_email_alias, $new_domain, $forward_to )
	{
		$this->setData( 'form_source'	, $new_email_alias );
		$this->setData( 'form_domain'	, $new_domain );
		$this->setData( 'form_dest'		, $forward_to );
	}
	
	final public function query()
	{
		$ch = curl_init ( $this->url );
		curl_setopt( $ch,	CURLOPT_RETURNTRANSFER	, true );
		curl_setopt( $ch,	CURLOPT_USERAGENT		, 'Opera/9.23 (Windows NT 5.1; U; en)' );
		curl_setopt( $ch,	CURLOPT_HTTPAUTH		, CURLAUTH_ANY );
		curl_setopt( $ch,	CURLOPT_SSL_VERIFYPEER	, false );
		curl_setopt( $ch,	CURLOPT_SSL_VERIFYHOST	, 2 );
		curl_setopt( $ch,	CURLOPT_POST			, 1 );
		curl_setopt( $ch,	CURLOPT_POSTFIELDS		, $this->data );
		
		return $this->formatResult( curl_exec( $ch ) );
	}
	
	final private function formatResult( $result )
	{
		$return = array();
		
		foreach( split( ' ', $result ) as $spl )
		{
			$data_split = split( '=', $spl );
			$return[ $data_split[0] ] = $data_split[1];
		}
		
		return ( $return['STATUS'] == 'OK' ) ? $return : false;
	}
}
?>
Thanks very much.
Unfortunately we have a new API used since Firefox Add-On version 2.0. I have not yet commented it. But the API which you use is still backward compatible.
I would like to post the new API. For the moment I'm a little busy.

Best regards,
saf

Re: API References 1.0

Posted: 27 Jun 2009, 19:34
by missinglink
Cool man, send me an email when it goes public and I'll update the class.

[update] Version 2.1 Class now available:
https://ssl.trashmail.net/forum/viewtop ... 2892#p2892

Re: API References 1.0

Posted: 27 Jun 2009, 19:38
by Admin
missinglink wrote:Cool man, send me an email when it goes public and I'll update the class.
Ok, no problem.