My activities New request

contact atmail support

PH: +61 (7) 5357-6605

support@atmail.com

  1. atmail help centre
  2. atmail 7 on-premises
  3. API

Follow

WebMail Client Mail API

Stewart -

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

Hint

All these APIs must be invoked after successful authentication.

Fetch Mail List

The Mail List resource returns the list of messages in the current folder within the given parameters.

Resource URI

http://domain.com/index.php/api/mail/list
Input parameters
PropertyDescription
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&hellip;", 
        "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
PropertyDescription
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
PropertyDescription
folder The folder name that to fetch, i.e. INBOX
uniqueId The unique message ID
Return Resource Properties
PropertyDescription
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
PropertyDescription
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

PropertyDescription
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
PropertyDescription
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
PropertyDescription
searchQuery The search string
Resource Properties
PropertyDescription
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&hellip;"
    },
    
    ...
]

NOTE: this will be expanded in the future to include extra search fields

Have more questions? Submit a request

Comments

  • Avatar
    Michael

    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"