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/?
- 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.
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"
$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|
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;
}
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
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.