Features > API

MailNuggets API

The API helps with the addition, removal, lookup and listing of temporary email addresses for your mailnuggets account. These email addresses (also referred to as 'throwaways' below) can be distributed to users whose emails may be piped to your remote script by a mailnuggets rule. When you no longer want that user to send email to your script, for example, you can delete that address with this API.

You can download a PHP class for accessing the API here. The API can be called using standard http GET requests, and responds with XML.

NOTES:
  • Throwaway names are always stored as lower case, and must be alphanumeric
  • Your version of PHP will need curl() and hash_mac()
  • The API returns XML, and meaningful errors

The PHP class supports the following methods:

listAllThrowaways()
  • Description: Lists the name, createddate, expiresdate for all temporary email addresses.
  • Required parameters: none
  • Optional parameters: none
Response example:

<?xml version="1.0" encoding="UTF-8"?>
<allthrowaways>
	<throwaway>
		<name>846543ef</name>
		<createddate>2010-11-23 03:31:44</createddate>
		<expiresdate>2999-10-26 00:00:00</expiresdate>
	</throwaway>
	<throwaway>
		<name>bb1eb24f</name>
		<createddate>2010-11-23 03:33:24</createddate>
		<expiresdate>2999-10-26 00:00:00</expiresdate>
	</throwaway>
</allthrowaways>


addThrowaway()
  • Description: Creates a new throwaway. If a throwawayname parameter is included, this will be used. Otherwise a random 8 character name will be assigned.
  • Required parameters: none
  • Optional parameters: throwawayname
Response example:

<?xml version="1.0" encoding="UTF-8"?>
	<success>
		<throwaway>
			<name>throwawayexamplename</name>
		</throwaway>
	</success>


lookupThrowaway()
  • Description: Gets the created and expired date for a throwaway. Returns an error if not found.
  • Required parameters: throwawayname
  • Optional parameters: none
Response example:

<?xml version="1.0" encoding="UTF-8"?>
	<throwaway>
		<name>throwawayexamplename</name>
		<createddate>2010-11-23 07:44:58</createddate>
		<expiresdate>2999-10-26 00:00:00</expiresdate>
	</throwaway>


removeThrowaway()
  • Description: Deletes a throwaway.
  • Required parameters: throwawayname
  • Optional parameters: none
Response example:

<?xml version="1.0" encoding="UTF-8"?>
	<success>1</success>


listEmails()
  • Description: Lists key information for emails received in last 48 hours.
  • Optional parameters: emailid
    Passing the emailid parameter will only display subsequently received emails in the list. The emailid is a proprietary identifier accesible for each email in this feed.
  • Does not contain the email message bodies, or attachments
Response example:

<?xml version="1.0" encoding="UTF-8"?>
	<emails>
		<email>
			<emailid>123456542</emailid>
			<subject>Example email 1</subject>
			<messageid>CAGjVw=r7mNKN8kyJFucGscMFdVRQLudrvd2NfLDC3ccQQDv7=Q@mail.gmail.com</messageid>
			<from>Van Stokes &lt;mail@vanstokes.com&gt;</from>
			<to>mail@apitester.mailnuggets.com</to>
			<hasattachment>0</hasattachment>
			<createdtimestamp>1317955927</createdtimestamp>
			<postsent>0</postsent>
			<postresponse></postresponse>
		</email>
	</emails>


repostEmail()
  • Description: rePOSTs any email received in last 48 hours.
  • Required parameters: emailid
    The emailid is a proprietary identifier accesible for each email in the listEmails feed.
  • POSTs to the original remote script, in the original format
Response example:

<?xml version="1.0" encoding="UTF-8"?>
	<success>
		<email>
			<emailid>56135</emailid>
		</email>
	</success>