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
- 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":"[email protected]","nb_redirections":"4","expiry_date":-1,"user":"tmp_hgtlqi","password":"6m2HEAsdD0VgoT"}
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"}
$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}
$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
- cmd: list-addresses
addresses: array of addresses, example: addresses[0]=[email protected]&addresses[1]=[email protected]&addresses[n]=...
dest: real email address, e.g. [email protected]
format: json (for software), human (for debugging)
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..."}]}
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":"[email protected]","dest":"[email protected]","nb_redirections":"4","nb_redirections_used":0,"ctime":"-1","expiry_date":"-1"},{"source":"[email protected]","dest":"[email protected]","nb_redirections":"4","nb_redirections_used":0,"ctime":"-1","expiry_date":"-1"},{"source":"[email protected]","dest":"[email protected]","nb_redirections":"4","nb_redirections_used":0,"ctime":"-1","expiry_date":"-1"}]}
HTTPS responds with HTTP return code 200:
Code: Select all
{"status":"error","reason":"$error_string","errorCode":$error_code}
$error_string: error string
$error_code: error code id
Delete an address
URL:
Code: Select all
https://ssl.trashmail.net/?api=1
- cmd: del
user: [email protected], e.g. [email protected] (with domain name)
passwd: password
format: json
Code: Select all
[{"status":"ok","reason":"account deleted","source":"[email protected]"}]
reason: "account deleted" string
source: username with domainname @trashmail.net
Example:
Code: Select all
[{"status":"ok","reason":"account deleted","source":"[email protected]"}]
HTTPS responds with HTTP return code 200:
Code: Select all
{"status":"error","reason":"$error_string","errorCode":$error_code}
$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
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
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.