Features > HTTP POST

Email to HTTP POST

While MailNuggets is designed for non-technical users, this section is for those comfortable configuring a remotely hosted script to receive POSTed data.

MailNuggets email forwarding over HTTP POST happens in real-time. Some options include:

Automatically store the POST response from your script (up to 256 characters). Use this to debug or keep verification data output by your remote script.
You can store POSTed emails at MailNuggets and view the text, HTML and raw versions, and the heirarchical data structure parsed from the raw email.
Create an unlimited number of receiving addresses manually, or via the API.

MailNuggets can send emails over HTTP POST using the following data structures: raw email, key value pairs, and JSON.

Raw Email
The raw email format sends the entire original email as the $_POST['email'] value. This is the best solution for those who wish to parse the email themselves. A recommended way to parse the raw email is Pear's Mail_mimeDecode.

Below is an example of a raw email.

From jonsmith@senderaddress.com  Tue Sep 28 23:27:49 2010
Return-Path: <jonsmith@senderaddress.com>
X-Original-To: mail@youraccount.mailnuggets.com
Delivered-To: mail@youraccount.mailnuggets.com
Received: from mail-bw0-f43.google.com (mail-bw0-f43.google.com [209.85.214.43])
	by mail.mailnuggets.com (Postfix) with ESMTP id 7D4F1E953
	for <mail@youraccount.mailnuggets.com>; Tue, 28 Sep 2010 23:27:49 -0400 (EDT)
Received: by bwz16 with SMTP id 16so396038bwz.2
        for <mail@youraccount.mailnuggets.com>; Tue, 28 Sep 2010 20:27:48 -0700 (PDT)
MIME-Version: 1.0
Received: by 10.204.23.77 with SMTP id q13mr656911bkb.191.1285730868456; Tue,
 28 Sep 2010 20:27:48 -0700 (PDT)
Received: by 10.204.46.225 with HTTP; Tue, 28 Sep 2010 20:27:48 -0700 (PDT)
Date: Wed, 29 Sep 2010 11:27:48 +0800
Message-ID: <AANLkTikph8GKV1Qkx9Pd=e7N++NEi9DkU2KfooRbe+Hy@mail.gmail.com>
Subject: Nice Weather Today
From: Jon Smith <jonsmith@senderaddress.com>
To: mail@youraccount.mailnuggets.com
Content-Type: multipart/alternative; boundary=0003255584e2b0ef5304915d8b00

--0003255584e2b0ef5304915d8b00
Content-Type: text/plain; charset=ISO-8859-1

The temperature is perfect today. I hope you get outside.
Later, Jon



--0003255584e2b0ef5304915d8b00
Content-Type: text/html; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable

<span class=3D"Apple-style-span" style=3D"border-collapse: separate; color:=
 rgb(0, 0, 0); font-family: Times; font-style: normal; font-variant: normal=
; font-weight: normal; letter-spacing: normal; line-height: normal; orphans=
: 2; text-indent: 0px; text-transform: none; white-space: normal; widows: 2=
; word-spacing: 0px; font-size: medium;"><span class=3D"Apple-style-span" s=
tyle=3D"color: rgb(34, 34, 34); font-family: Verdana,Arial,sans-serif; font=
-size: 16px;">The temperature is <span style=3D"font-weight: bold;">perfect=
</span> today. I hope you get outside.<br style=3D"margin: 0px; padding: 0p=
x;">
Later, Jon

--0003255584e2b0ef5304915d8b00--

Key Value Pairs
This option is the simplest way to receive your email POST. The following sections are sent as $_POST array keys with their corresponding values:

return-path
x-original-to
delivered-to
mime-version
date
message-id
subject
from
to
content-type
content-transfer-encoding-html
content-transfer-encoding
body
body_html
attachment[IndexValue][body]
attachment[IndexValue][content-type]
attachment[IndexValue][size]
attachment[IndexValue][name]
message-id-hash

Below is an example of the keys and values used for sending email parts in the $_POST array.


[return-path] => <jonsmith@senderaddress.com>
[x-original-to] => mail@youraccount.mailnuggets.com
[delivered-to] => mail@youraccount.mailnuggets.com
[mime-version] => 1.0
[date] => Wed, 29 Sep 2010 11:14:07 +0800
[message-id] => <AANLkTinGg8S=jDO+48B+Fg36FQS6FapXCsKGdApncU4N@mail.gmail.com>
[subject] => Nice Weather Today
[from] => Jon Smith <jonsmith@senderaddress.com>
[to] => mail@youraccount.mailnuggets.com
[content-type] => multipart/alternative; boundary=0016e6d7756ac0595804915d5abe
[body] => The temperature is perfect today.  I hope you get outside.
Later, Jon


[body_html] => The temperature is <span style="font-weight: bold;">perfect </span>today. I hope you get outside. <br>Later, Jon<br>
[message-id-hash] => ecb7a02424e3a8eb96f6c8a1da9a573e

Delivered-to may be an Array
The delivered-to value may be an array if the mail was sent to one or more forwarding addresses prior to reaching the mail@youraccount.mailnuggets.com address. So, if your email goes like this: forwardingaddress@gmail.com -> mail@youraccount.mailnuggets.com -> POST to custom script, the delivered-to[0] value should be mail@youraccount.mailnuggets.com and delivered-to[1] value should be forwardingaddress@gmail.com.

Validate POSTs Using the message-id-hash
The message-id-hash is an MD5 hash generated by concatenating the message-id and API secret key like so: md5($_POST['message-id'] . $apiSecretKey). This can be used to add assurance that POSTs to your remote script are from the MailNuggets server. NOTE: The message-id includes the '<' '>' that enclose it.

Send Attachments to Amazon S3
When attachments are sent to Amazon S3, the POSTed attachment array values will look like:

attachment[IndexValue][s3-bucket-name]
attachment[IndexValue][s3-object-name]
attachment[IndexValue][content-type]
attachment[IndexValue][size]
attachment[IndexValue][name]

Send Attachments to Google Docs
When attachments are sent to Google Docs, the POSTed attachment array values will look like:

attachment[IndexValue][google-docs-collection-id]
attachment[IndexValue][google-docs-collection-name]
attachment[IndexValue][google-docs-location]
attachment[IndexValue][google-docs-id]
attachment[IndexValue][content-type]
attachment[IndexValue][size]
attachment[IndexValue][name]

JSON
This option POSTs a JSON formatted string as the $_POST['email'] value. This string includes the entire email including headers, body parts and attachments (which are base64 encoded).

This is the easiest way to POST your email while retaining the heirarchical structure of the header and body parts. You can import the JSON string and convert it to a PHP object or array using json_decode() in PHP 5.2.0 or greater.

Below is an example of a JSON formatted POST.

{"headers":{"from jonsmith@senderaddress.com  tue sep 28 23":"34:44 2010","return-path":"<jonsmith@senderaddress.com>","x-original-to":"mail@youraccount.mailnuggets.com","delivered-to":"mail@youraccount.mailnuggets.com","received":["from mail-bw0-f43.google.com (mail-bw0-f43.google.com [209.85.214.43])by mail.mailnuggets.com (Postfix) with ESMTP id DFFB9E953for <mail@youraccount.mailnuggets.com>; Tue, 28 Sep 2010 23:34:43 -0400 (EDT)","by bwz16 with SMTP id 16so399547bwz.2for <mail@youraccount.mailnuggets.com>; Tue, 28 Sep 2010 20:34:43 -0700 (PDT)","by 10.204.101.133 with SMTP id c5mr613367bko.212.1285731281913; Tue,28 Sep 2010 20:34:41 -0700 (PDT)","by 10.204.46.225 with HTTP; Tue, 28 Sep 2010 20:34:41 -0700 (PDT)"],"mime-version":"1.0","date":"Wed, 29 Sep 2010 11:34:41 +0800","message-id":"<AANLkTinooTpmBGmi0MWiDHSEwoq0tZHbnb581d5SSNPs@mail.gmail.com>","subject":"Nice Weather Today","from":"Jon Smith <jonsmith@senderaddress.com>","to":"mail@youraccount.mailnuggets.com","content-type":"multipart\/alternative; boundary=0016e6d99b7d55c5e704915da462"},"ctype_primary":"multipart","ctype_secondary":"alternative","ctype_parameters":{"boundary":"0016e6d99b7d55c5e704915da462"},"parts":[{"headers":{"content-type":"text\/plain; charset=ISO-8859-1"},"ctype_primary":"text","ctype_secondary":"plain","ctype_parameters":{"charset":"ISO-8859-1"},"body":"The temperature is perfect today. I hope you get outside.\nLater, Jon\n\n\n"},{"headers":{"content-type":"text\/html; charset=ISO-8859-1"},"ctype_primary":"text","ctype_secondary":"html","ctype_parameters":{"charset":"ISO-8859-1"},"body":"The temperature is <span style=\"font-weight: bold;\">perfect<\/span> today. I hope you get outside.<br>Later, Jon<br> \n\n"}]}

When converted to a PHP object it would be structured as so:

Sample Code
Here you can find a sample PHP script that receives a POSTed emails, parses them and saves attachments. From this you can access important data and save attachments.