Page 1 of 1

API References 2.1

Posted: 22 Jul 2009, 13:04
by Admin
TrashMail References API Version 2.0

This is the second version of TrashMail'sl API documentation to write tools to use this 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/?api=1
Parameters:
  • cmd: create-address = tell TrashMail-Server to create an address

    form_source: TrashMail user name to use. Its usually a random name with 8 caracters.

    form_domain: TrashMail user domain name to use. E.g. "trashmail.net", "rcpt.at"...

    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 displayed on the administration 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.

    format: json = output would be in JSON format, example: {"status":"ok","source":"tmp_hgxlqi","domain":"trashmail.net","real":"foo@bar.tld","nb_redirections":"4","expiry_date":-1,"user":"tmp_hgtlqi","password":"6m2HEAsdD0VgoT"}
Return values
The return values are included in a JSON structure in all cases.

1. On success:

Code: Select all

{"status":"ok","source":"$my_source","domain":"$my_domainname","real":"$my_form_dest","nb_redirections":"$my_nb_forwards","expiry_date":$my_days,"user":$my_usernamei","password":"$my_password"}
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
$my_username: User name created on server
$my_password: Generated password from server

2. On error:
HTTPS responds with HTTP return code 200:

Code: Select all

{"status":"error","reason":"$error_string","errorCode":$error_code}
Return arguments:
$error_string: error string
$error_code: error code id


List status about existing addresses
Trashmail: API request: https://ssl.trashmail.net/?api=1
URL:

Code: Select all

https://ssl.trashmail.net/?api=1
Parameters: Return values:
JSON or human viewable structure. Only the JSON structure is described here. Human view should ony be used for debugging.

On success:

Code: Select all

{"status":"ok","addresses":[{"...JSON_ARRAY..."}]}
status: ok
addresses: JSON array: source: source_address, dest: real_email_address, nb_redirections: total_number_of_forwards, nb_redirections_used: number_of_forwards_used, expiry_date: unix_timestamp_date_of_expiration

Example:

Code: Select all

{"status":"ok","addresses":[{"source":"tmp_hgtlqi@kurzepost.de","dest":"foo@bar.tld","nb_redirections":"4","nb_redirections_used":0,"ctime":"-1","expiry_date":"-1"},{"source":"tmp_hixsop@kurzepost.de","dest":"foo@bar.tld","nb_redirections":"4","nb_redirections_used":0,"ctime":"-1","expiry_date":"-1"},{"source":"tmp_zcgozw@kurzepost.de","dest":"foo@bar.tld","nb_redirections":"4","nb_redirections_used":0,"ctime":"-1","expiry_date":"-1"}]}
On error:
HTTPS responds with HTTP return code 200:

Code: Select all

{"status":"error","reason":"$error_string","errorCode":$error_code}
Return arguments:
$error_string: error string
$error_code: error code id


Delete an address
URL:

Code: Select all

https://ssl.trashmail.net/?api=1
Parameters: On success:

Code: Select all

[{"status":"ok","reason":"account deleted","source":"username@trashmail.net"}]
status: ok
reason: "account deleted" string
source: username with domainname @trashmail.net

Example:

Code: Select all

[{"status":"ok","reason":"account deleted","source":"tmp_hixsop@trashmail.net"}]
On error:
HTTPS responds with HTTP return code 200:

Code: Select all

{"status":"error","reason":"$error_string","errorCode":$error_code}
Return arguments:
$error_string: error string
$error_code: error code id


Example how to use this API:
The Mozilla Firefox TrashMail Add-On version >= 2.0.0 uses the new API and provides a debugging possibility to see the communication between client and server.

Download Mozilla Firefox TrashMail Add-On at:
https://addons.mozilla.org/firefox/1813/

After installation, type in the address bar:

Code: Select all

about:config
Then set the variable trashmail.debugMode to 2.
If the variable does not exists, then add it.

From now on, each communication between the TrashMail Add-On and the TrashMail-server is logged in the error console of Mozilla Firefox.

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 2.0

Posted: 12 Dec 2009, 01:50
by Lobe
I am having trouble with the delete API.
For example, I sent this to create my account (These are POST arguments to https://ssl.trashmail.net/):

Code: Select all

{'form_nb_redirections': '10', 'form_whitelisting': '0', 'format': 'json', 'form_expire_days': '10', 'cmd': 'create-address', 'create_submit': 'Create disposable email address', 'form_source': 'fymmcamdwl', 'api': '1', 'delete_msg_chk': '0', 'form_dest': 'test@a.com'}
And got this response:

Code: Select all

{'status': 'ok', 'real': 'test@a.com', 'domain': 'trashmail.net', 'nb_redirections': '10', 'source': 'fymmcamdwl', 'expiry_date': 1261442731, 'user': 'fymmcamdwl', 'password': 'AWmU82n2vLAG8M'}
Which all seems fine. However, when I ask the server to delete the email by sending this:

Code: Select all

{'api': '1', 'password': 'AWmU82n2vLAG8M', 'cmd': 'del', 'user': 'fymmcamdwl', 'format': 'json'}
I get this response:

Code: Select all

{'status': 'error', 'errorCode': 1000, 'reason': 'invalid user or password'}
What am I doing wrong?

Re: API References 2.0

Posted: 12 Dec 2009, 09:41
by Admin
Lobe wrote:What am I doing wrong?
Try to replace the keyname "password" by "passwd".

If you want to understand better how all this works, you could install the TrashMail.net Firefox Add-On, then type "about:config" in the browser, and set the variable "trashmail.debugMode" to 2. Then open in Firefox the "Error console" and try to use the TrashMail.net Firefox Add-On. You will see in the error console all network operations between the Add-On and the TrashMail.net web server.

A delete operation would look like this:

Code: Select all

Trashmail: API request: https://ssl.trashmail.net/?API=1
[object]
	user=[string] tmp_fdgqik
	passwd=[string] 6hTVboroSDiQQ5
	cmd=[string] del
	format=[string] json

Code: Select all

Trashmail: API response: 200:[{"status":"ok","reason":"account deleted","source":"tmp_fdgqik@trashmail.net"}]
Best regards,
Admin

Re: API References 2.1

Posted: 18 Apr 2010, 19:16
by missinglink

Code: Select all

<?php
    /**
    * Trashmail API ver 2 PHP Class
    * Used to create, list, delete Trashmail addresses
    *
    * @name Trashmail API ver 2 PHP Class
    * @description Used to create, list, delete Trashmail addresses
    * @version 2
    * @author Peter Johnson
    * @email nospam_replyok@trashmail.net
    * @license Free
    *
    * @example
      $tm = new Trashmail();
      $result = $tm->create( "test439957", "rcpt.at", "e@example.com" );
      $result = $tm->listAddresses( array( "test439957@rcpt.at" ), "e@example.com" );
      $result = $tm->delete( "test439957@rcpt.at", "eyQ03ZuEBUwXfU" );
      print_r( $result );
    *
    * @more
      $tm = new Trashmail( true ); // Unlimited forwards and expiry.
      $result = $tm->create( "test439957", "rcpt.at", "e@example.com" );
      print_r( $tm->getHttpInfo() ); // Return information about the CURL request.
      var_dump( $tm->getUserAgent() ); // Output the user agent string you used.
      var_dump( $tm->getRequest() ); // Output the request string you sent.
      var_dump( $tm->getRawResponse() ); // Output the raw response string.
    */

    final class Trashmail
    {
       private $url = "https://ssl.trashmail.net/?api=1";
       private $curl;
       private $post;
       private $request;
       private $response;
       private $useragent;
       private $httpinfo;
       private $unlimited;

       final public function __construct( $unlimited = false )
       {
           $this->setUserAgent();
           $this->unlimited = is_bool( $unlimited ) && $unlimited;
       }

       final public function create( $alias = "a", $domain = "trashmail.net", $to = "e@example.com", $redirect = 10, $expire = 7, $notify = true, $whitelist = 0 )
       {
          $this->clearData();
          $this->setData( "cmd", "create-address" );
          $this->setData( "form_source", $alias );
          $this->setData( "form_domain", $domain );
          $this->setData( "form_dest", $to );
          $this->setData( "form_nb_redirections", $this->unlimited ? "-1" : $redirect );
          $this->setData( "form_expire_days", $this->unlimited ? "-1" : $expire );
          $this->setData( "form_whitelisting", $whitelist );
          $this->setData( "delete_msg_chk", $notify ? 1 : 0 );
          $this->setData( "create_submit", "Create disposable email address" );
          return $this->query();
       }

       final public function listAddresses( $addresses = array(), $to = "e@example.com" )
       {
          $this->clearData();
          $this->setData( "cmd", "list-addresses" );
          foreach( $addresses as $k => $v ) $this->setData( "addresses[".$k."]", $v );
          $this->setData( "dest", $to );
          return $this->query();
       }

       final public function delete( $to = "e@example.com", $password = "pass" )
       {
          $this->clearData();
          $this->setData( "cmd", "del" );
          $this->setData( "user", $to );
          $this->setData( "passwd", $password );
          return $this->query();
       }

       final private function clearData(){ $this->post = array( "format" => "json" ); }
       final public function setData( $id, $val ){ $this->post[ $id ] = $val; }
       final public function getHttpInfo(){ return $this->httpinfo; }
       final public function getUserAgent(){ return $this->useragent; }
       final public function getRequest(){ $this->flattenPost(); return $this->request; }
       final public function getRawResponse(){ return $this->response; }

       final private function flattenPost()
       {
           $this->request = "";
           foreach( $this->post as $k => $v )
               $this->request .= $k . "=" . rawurlencode( (string) $v ) . "&";
           $this->request = substr( $this->request, 0, -1 );
       }

       final private function catchErrors()
       {
          if( !isset( $this->httpinfo["http_code"] ) || $this->httpinfo["http_code"] != 200 ) throw new Exception( "Request error" );
          else if( $this->response === false ) throw new Exception( "Curl error: " . curl_error( $this->curl ) );
          else if( empty( $this->response ) ) throw new Exception( "Response empty");
       }

       final public function setUserAgent( $agent = NULL )
       {
           if( $agent === NULL )
           {
               $curlVersion = curl_version();
               $this->useragent = "Trashmail PHP Client/0.1";
               $this->useragent .= " (php:" . PHP_VERSION;
               $this->useragent .= isset( $curlVersion["version"] ) ? "; curl:" . $curlVersion["version"] : "";
               $this->useragent .= ")";
           }
           else $this->useragent = $agent;
       }

       final public function query()
       {
          $this->curl = curl_init( $this->url );

          curl_setopt( $this->curl, CURLOPT_RETURNTRANSFER, true );
          curl_setopt( $this->curl, CURLOPT_USERAGENT, $this->getUserAgent() );
          curl_setopt( $this->curl, CURLOPT_HTTPAUTH, CURLAUTH_ANY );
          curl_setopt( $this->curl, CURLOPT_SSL_VERIFYPEER, false );
          curl_setopt( $this->curl, CURLOPT_SSL_VERIFYHOST, false );
          curl_setopt( $this->curl, CURLOPT_POST, 1 );
          curl_setopt( $this->curl, CURLOPT_POSTFIELDS, $this->getRequest() );

          $this->response = curl_exec( $this->curl );
          $this->httpinfo = curl_getinfo( $this->curl );
          $this->catchErrors();

          return json_decode( $this->response );
       }
    }
?>

Re: API References 2.1

Posted: 31 Aug 2011, 13:33
by XopHeT
Hello everybody!
Where i can see all of errorcodes and their description that API may return?

Re: API References 2.1

Posted: 03 Oct 2011, 14:19
by Admin
XopHeT wrote:Hello everybody!
Where i can see all of errorcodes and their description that API may return?
It the new API which will be the 3.0 API. I will post an official PDF document when I have translated it to english.
I will do it soon.