PROBLEM
How can I use the WebMail Client mail API?
ENVIRONMENT
- On-Premise Server + WebMail Installations: Version 6.0 > Current Version
- Webmail Only Installations: Version 6.0 > Current Version
CAUSE
WebMail Client mail API requirement.
RESOLUTION
Resource URI
http://domain.com/index.php/api/mail/list
Input parameters
Property | Description |
---|---|
SessionID | The session id for the logged in account you want to access (must be passed in query string) |
folder | The folder name that to fetch, i.e. INBOX |
count | How many results to return (defaults to 3) |
offset | Start fetching results from this offset position (defaults to 0) |
HTTP GET
Returns a JSON encoded string representing the requested emails
Example
http://domain.com/index.php/api/mail/list {
SessionID : folder : 'INBOX', count : 1
offset : 0 }
Returned JSON example
[ { "basicHeaders" : { "message-id" : "<1640f9d4d6ae807dea9a61c4f0abd797889da509@atmail.local>", "from_name" : "", "from_email" : "james@domain.com", "from" : "james@domain.com", "to_name" : "", "to_email" : "james@atmail.com", "to" : "james@atmail.com", "subject" : "Fwd: Welcome to your new email account", "date" : "Sat, 22 Sep 2012 05:02:31 -0700", "content-type" : "text\/plain; charset=UTF-8" }, "preview" : "-------- Original Message ---------- WELCOME TO ATMAIL Hello and\nwelcome to your new email account. Please keep the instructions b…", "UID" : "2" }, ... ]
Mail Status
The Mail Status request returns a single email based on the given folder name and unique message ID.
Resource URI
http://domain.com/index.php/api/mail/status
Return Resource Properties
Property | Description |
---|---|
flags | An array of predefined flags for mail |
exists | The the total mails in folder |
recent | The count of new email |
unseen | The unread count of email |
uidvalidity | The time stamp |
HTTP GET
Returns a JSON encoded string representing the requested email
Example
http://domain.com/index.php/api/mail/status
Returned JSON
{ "flags" : [["\\Answered","\\Flagged","\\Deleted","\\Seen","\\Draft"]], "exists" : "10", "recent" : "0", "unseen" : 1, "uidvalidity":1350352752 }
Mail View
The Mail View request returns a single email based on the given folder name and unique message ID.
Resource URI
http://domain.com/index.php/api/mail/view
Input parameters
Property | Description |
---|---|
folder | The folder name that to fetch, i.e. INBOX |
uniqueId | The unique message ID |
Return Resource Properties
Property | Description |
---|---|
UID | The unique ID of the message |
cc | The names and email addresses of the carbon copy recipients of the message |
content-type | The content type that the message contains |
date | The date the message was received |
from | The name and email of the senders of the message |
from_email | The email of the sender of the message |
from_name | The name of the sender of the message |
message-id | The id string of the message |
subject | The subject of the message |
to | The names and emails of the recipients of the message |
to_email | The emails of the recipients of the message |
to_name | The names of the recipients of the message |
preview | The first section of the email body |
HTTP GET
Returns a JSON encoded string representing the requested email
Example
http://domain.com/index.php/api/mail/view { folder : 'INBOX', uniqueId: 3 }
Returned JSON
[ { "bodyPreparedHtml" : "Hi Jackson ...", "cids" : [ ], "forcedAttachments": [ ], "forcedInlines" : [ ], "headers" : { "UserPhoto" : false, "content-type" : "multipart/alternative; boundary=\"=_e6ce25a1782bbcfa7d48c4164f4b97cb\"", "date" : "Fri, 10 Jun 2011 16:34:18 +1000", "dateraw" : "Fri, 10 Jun 2011 16:34:18 +1000", "email" : "cbaird@apitest.com", "epoch" : 1307687658, "from" : "\"Charli Baird\" <cbaird@apitest.com>", "fromOrigional" : "\"Charli Baird\" <cbaird@apitest.com>", "hasattachments": "yes", "message-id" : "<00a5982e4de99cf74e1e5d5e18fdaa7a17d3ab24@domain.com>", "mime-version" : "1.0", "name" : "Charli Baird", "priority" : "normal", "reply-to" : "\"Charli Baird\" <cbaird@apitest.com>", "size" : "3 KB", "sizeraw" : 3563, "subject" : "Re: Figures for new ad", "to" : "\"Jackson McLean\" <jmclean@apitest.com>", "uniqueid" : "3" }, "headersOriginal" : { "content-type": "multipart/alternative; boundary=\"=_e6ce25a1782bbcfa7d48c4164f4b97cb\"", "date" : "Fri, 10 Jun 2011 16:34:18 +1000", "from" : "\"Charli Baird\" <cbaird@apitest.com>", "message-id" : "<00a5982e4de99cf74e1e5d5e18fdaa7a17d3ab24@domain.com>", "mime-version": "1.0", "subject" : "Re: Figures for new ad", "to" : "\"Jackson McLean\" <jmclean@apitest.com>" } } ]
Message Thread View
The Message Thread View Resource returns all emails in a thread based on the given folder name and unique message ID.
Resource URI
http://domain.com/index.php/api/mail/messagethread/
Input parameters
Property | Description |
---|---|
folder | The folder name that to fetch, i.e. INBOX |
uniqueId | The unique message ID |
HTTP GET
Returns a JSON encoded string representing the requested emails
Example
http://domain.com/index.php/api/mail/messagethread { folder : 'INBOX', uniqueId : 2 }
Returned JSON
[ { "bodyPreparedHtml" : "Hi Jackson, ...", "cids" : [ ], "currentThread" : [ "3", "5", "2" ], "forcedAttachments": [ ], "forcedInlines" : [ ], "headers" : { "UserPhoto" : false, "content-type" : "multipart/alternative; boundary=\"=_e6ce25a1782bbcfa7d48c4164f4b97cb\"", "date" : "Fri, 10 Jun 2011 16:34:18 +1000", "dateraw" : "Fri, 10 Jun 2011 16:34:18 +1000", "email" : "cbaird@apitest.com", "envelope-to" : "jmclean@apitest.com", "epoch" : 1307687658, "from" : "\"Charli Baird\" <cbaird@apitest.com>", "fromOrigional" : "\"Charli Baird\" <cbaird@apitest.com>", "hasattachments": "yes", "in-reply-to" : "<abb7a25814d3291dcb2a74c85a59a02377c3a9d4@domain.com>", "message-id" : "<00a5982e4de99cf74e1e5d5e18fdaa7a17d3ab24@domain.com>", "mime-version" : "1.0", "name" : "Charli Baird", "priority" : "normal", "received" : "from localhost ([127.0.0.1]) by domain.com with esmtp (Exim 4.72) (envelope-from <cbaird@apitest.com>) id 1QUvIQ-0002Hs-GM for jmclean@apitest.com; Thu, 09 Jun 2011 23:34:18 -0700", "reply-to" : "\"Charli Baird\" <cbaird@apitest.com>", "return-path" : "<cbaird@apitest.com>", "size" : "3 KB", "sizeraw" : 3563, "subject" : "Re: Figures for new ad", "to" : "\"Jackson McLean\" <jmclean@apitest.com>", "uniqueid" : "3", "x-mailer" : "Atmail 7.1.0" }, "headersOriginal" : { "content-type": "multipart/alternative; boundary=\"=_e6ce25a1782bbcfa7d48c4164f4b97cb\"", "date" : "Fri, 10 Jun 2011 16:34:18 +1000", "envelope-to" : "jmclean@apitest.com", "from" : "\"Charli Baird\" <cbaird@apitest.com>", "in-reply-to" : "<abb7a25814d3291dcb2a74c85a59a02377c3a9d4@domain.com>", "message-id" : "<00a5982e4de99cf74e1e5d5e18fdaa7a17d3ab24@domain.com>", "mime-version": "1.0", "received" : "from localhost ([127.0.0.1]) by domain.com with esmtp (Exim 4.72) (envelope-from <cbaird@apitest.com>) id 1QUvIQ-0002Hs-GM for jmclean@apitest.com; Thu, 09 Jun 2011 23:34:18 -0700", "return-path" : "<cbaird@apitest.com>", "subject" : "Re: Figures for new ad", "to" : "\"Jackson McLean\" <jmclean@apitest.com>", "x-mailer" : "Atmail 7.1.0" } }, { "attachmentsList" : [ { "fileTypeName" : "Microsoft Word spreadsheet", "filenameFS" : "INBOX5Data1.xlsx", "filenameOriginal": "Data1.xlsx", "iconClass" : "default", "mimeType" : "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "sizeRaw" : 19536 } ], "bodyPreparedHtml" : "<html><body><span class= ...", "cids" : [ ], "forcedAttachments": [ { "fileTypeName" : "Microsoft Word spreadsheet", "filenameFS" : "INBOX5Data1.xlsx", "filenameOriginal": "Data1.xlsx", "iconClass" : "default", "mimeType" : "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "sizeRaw" : 19536 } ], "forcedInlines" : [ ], "headers" : { "UserPhoto" : false, "content-type" : "multipart/mixed; boundary=\"=_b86b1fffb2b23b1794f7bc928d30e512\"", "date" : "Fri, 10 Jun 2011 16:28:44 +1000", "dateraw" : "Fri, 10 Jun 2011 16:28:44 +1000", "email" : "jmclean@apitest.com", "epoch" : 1307687324, "from" : "\"Jackson McLean\" <jmclean@apitest.com>", "fromOrigional" : "\"Jackson McLean\" <jmclean@apitest.com>", "hasattachments": "yes", "in-reply-to" : "<52627954f5661f1b1640c803c9301e016ae2d494@domain.com>", "message-id" : "<abb7a25814d3291dcb2a74c85a59a02377c3a9d4@domain.com>", "mime-version" : "1.0", "name" : "Jackson McLean", "priority" : "normal", "reply-to" : "\"Jackson McLean\" <jmclean@apitest.com>", "size" : "22 KB", "sizeraw" : 22593, "subject" : "Re: Figures for new ad", "to" : "\"Charli Baird\" <cbaird@apitest.com>", "uniqueid" : "5", "x-mailer" : "Atmail 7.1.0" }, "headersOriginal" : { "content-type": "multipart/mixed; boundary=\"=_b86b1fffb2b23b1794f7bc928d30e512\"", "date" : "Fri, 10 Jun 2011 16:28:44 +1000", "from" : "\"Jackson McLean\" <jmclean@apitest.com>", "in-reply-to" : "<52627954f5661f1b1640c803c9301e016ae2d494@domain.com>", "message-id" : "<abb7a25814d3291dcb2a74c85a59a02377c3a9d4@domain.com>", "mime-version": "1.0", "subject" : "Re: Figures for new ad", "to" : "\"Charli Baird\" <cbaird@apitest.com>", "x-mailer" : "Atmail 7.1.0" } }, { "bodyPreparedHtml" : "<html><body>Hello Jackson, <div><br /></div> ...", "cids" : [ ], "forcedAttachments": [ ], "forcedInlines" : [ ], "headers" : { "UserPhoto" : false, "content-type" : "multipart/alternative; boundary=\"=_4863b89f01e5806f73d391f64a15fe43\"", "date" : "Fri, 10 Jun 2011 16:21:16 +1000", "dateraw" : "Fri, 10 Jun 2011 16:21:16 +1000", "email" : "cbaird@apitest.com", "envelope-to" : "jmclean@apitest.com", "epoch" : 1307686876, "from" : "\"Charli Baird\" <cbaird@apitest.com>", "fromOrigional" : "\"Charli Baird\" <cbaird@apitest.com>", "hasattachments": "no", "message-id" : "<52627954f5661f1b1640c803c9301e016ae2d494@domain.com>", "mime-version" : "1.0", "name" : "Charli Baird", "priority" : "normal", "received" : "from localhost ([127.0.0.1]) by domain.com with esmtp (Exim 4.72) (envelope-from <cbaird@apitest.com>) id 1QUv5o-0002EY-NL for jmclean@apitest.com; Thu, 09 Jun 2011 23:21:16 -0700", "reply-to" : "\"Charli Baird\" <cbaird@apitest.com>", "return-path" : "<cbaird@apitest.com>", "size" : "1 KB", "sizeraw" : 958, "subject" : "Figures for new ad", "to" : "\"Jackson McLean\" <jmclean@apitest.com>", "uniqueid" : "2", "x-mailer" : "Atmail 7.1.0" }, "headersOriginal" : { "content-type": "multipart/alternative; boundary=\"=_4863b89f01e5806f73d391f64a15fe43\"", "date" : "Fri, 10 Jun 2011 16:21:16 +1000", "envelope-to" : "jmclean@apitest.com", "from" : "\"Charli Baird\" <cbaird@apitest.com>", "message-id" : "<52627954f5661f1b1640c803c9301e016ae2d494@domain.com>", "mime-version": "1.0", "received" : "from localhost ([127.0.0.1]) by domain.com with esmtp (Exim 4.72) (envelope-from <cbaird@apitest.com>) id 1QUv5o-0002EY-NL for jmclean@apitest.com; Thu, 09 Jun 2011 23:21:16 -0700", "return-path" : "<cbaird@apitest.com>", "subject" : "Figures for new ad", "to" : "\"Jackson McLean\" <jmclean@apitest.com>", "x-mailer" : "Atmail 7.1.0" } } ]
Send Email
This request is used to send a message using the authenticated users account.
Resource URI
http://domain.com/index.php/api/mail/send
Input Parameters
Property | Description |
---|---|
emailTo | The email addresses to send the email to |
emailCc | The email addresses to carbon copy the email to |
emailBcc | The email addresses to blind carbon copy the email to |
emailSubject | The subject of the email |
emailBodyHtml | The html contents of the body |
emailBodyText | The plain text contents of the body (if emailBodyHtml is not included) |
attachments | The locations of the files to attach, comma seperated |
relatedMessageMessageID | The previous message UID associated with this reply |
threadID | The thread in which this message should be contained |
readReceiptRequested | Whether a read receipt is requested: 1 or true = yes, 0 or false = no |
HTTP POST
Returns a JSON encoded string containing the list of recipients that the message was sent to and any errors that occurred.
Request Example
http://domain.com/index.php/api/mail/send { emailTo : 'james@atmail.local', emailBcc : 'ie@iinet.net.au', emailCc : 'james@iinet.net.au', emailSubject : 'Test Message', emailBodyText : 'Test Message Content' }
Returned JSON
{ "final_recipients": ["james@atmail.com", "james@iinet.net.au", "ie@iinet.net.au"], "rcptLog" : ["james@atmail.com", "james@iinet.net.au", "ie@iinet.net.au"], "error" : null }
Move Mail between folders / Delete Mail
The Mail List request returns a list of messages in the current folder within the given parameters.
Resource URI
http://domain.com/index.php/mail/mail/movetofolder
Input parameters
Property | Description |
---|---|
fromFolder | The original folder |
toFolder | The destination folder |
mailId | The unique messages to be move, must be an array of IDs |
UID | The unique message id to be move |
listFolder | This parameter must be set the same as fromFolder |
disableThread | Whether or not to disable thread |
expectJson | MUST set to 1 in order to get JSON response from server |
actuallyDelete | 1- perform actual delete; 0- put to Trash |
HTTP GET
Returns a JSON encoded string representing the execute result
Example
http://domain.com/index.php/mail/mail/movetofolder { disableThread: true, expectJson : true, fromFolder : 'INBOX', listFolder : 'INBOX', 'mailId[]' : 4, toFolder : 'INBOX.Trash' } or { disableThread: true, expectJson : true, fromFolder : 'INBOX', listFolder : 'INBOX', UID' : 4, toFolder : 'INBOX.Trash' }
Returned JSON
{"result":"success"}
Mail Search
The Mail Search request returns information about the latest email that matches a given search parameter.
Resource URI
http://domain.com/index.php/api/mail/search
Input Parameters
Property | Description |
---|---|
searchQuery | The search string |
Resource Properties
Property | Description |
---|---|
UID | The unique ID of the message |
cc | The names and email addresses of the carbon copy recipients of the message |
content-type | The content type that the message contains |
date | The date the message was received |
from | The name and email of the senders of the message |
from_email | The email of the sender of the message |
from_name | The name of the sender of the message |
message-id | The id string of the message |
subject | The subject of the message |
to | The names and emails of the recipients of the message |
to_email | The emails of the recipients of the message |
to_name | The names of the recipients of the message |
preview | The first section of the email body |
HTTP GET
Returns a JSON encoded string containing the details of the requested email
Example
http://domain.com/index.php/api/mail/search { searchQuery : 'james' }
Returned JSON
[ { "UID" : "1", "basicHeaders": { "from_name" : "", "from_email" : "james@atmail.com", "from" : "james@atmail.com", "subject" : "Welcome to your new email account", "date" : "Thu, 20 Sep 2012 18:03:51 +0000", "to_name" : "", "to_email" : "james@iinet.net.au", "to" : "james@iinet.net.au", "message-id" : "<1d6146a9207cf06dc9fab09d5ea6f627d804e4ce@atmail.local>", "content-type" : "multipart\/alternative; boundary=\"=_d9aaf841e8b0cc0974a3cb5aa328002d\"" }, "preview" : "WELCOME TO ATMAIL\n\n\tHello and welcome to your new email account. Please keep the\ninstructions below for details on how to setu…" }, ... ]
NOTE: this will be expanded in the future to include extra search fields
Move Mail between folders / Delete Mail
Could you review that API? Because it didn't work as you explained...
Firstly the index.php/mail/mail/movetofolder wants a POST and not a GET request as explained. Secondly with a Post the result is: General Error.
Passed Parameters:
Parameters: {
SessionID: 'xyz',
disableThread: true,
expectJson : true,
fromFolder : 'INBOX',
listFolder : 'INBOX',
UID' : 15,
toFolder : 'INBOX.Trash'
}
and in the header:
"x-csrf", "1"