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"