Feature Wiki

Information about planned and released features

Tabs

Get mail content over webservice with method

Page Overview

[Hide]

1 Requirements

In the Ilias webservice SOAP there is the possiblity to send mails and to ask if a new mail has arrive. We need a function to get the content (Subject, Recipient, Sender, Content, ...) for a specific mail to display it to the user for an Android application.
For example the signature could be: getMailContent(sid, usr_id, mail_id): String.

2 Additional Information

3 Discussion

Michael Jansen, 11 Apr 2014: I support this request.

Jour Fixe 14 April 2014: We support the request in general and schedule it for 4.5. The following questions/issues should be clarified:

  • We would omit the user_id, the user id should be determined by the sid. (only mails by the corresponding user should be returned).
  • Where do you get the mail_id from? HasNewMail returns only a boolean. We think a second function getUnreadMails(sid) may be necessary, returning subjects, sender, timestamp and ids of unread mails (without content).
  • How are attachments supposed to be handled? They must not be send immediately with the getMailContent function.
Please provide answers to the questions and reschedule this topic on the JF agenda.

Sven Mielke, 19 August 2014: Next month a student group of HSW (Hochschule Weserbergland) starts to implement an Android app that should be able to receive mails. I suggest the following new SOAP functions:

  • getMailboxTree(sid) : returns a XML file that contains all mail folders (ID and name) under the root folder. (use: class.ilMailbox.php)
  • getMailsOfFolder(sid,folder_id,[filter]) : returns a XML file that contains a list of details of the mails of a given folder. These details would be id, title, time, attachments, sender ...  (use: class.ilMail.php)
  • getMail(sid,mail_id, [attachment_flag]) : returns the mail itself. (use: class.ilMail.php)
Does these suggestions match this feature request?

Martin Pelke, 04. Nov 2014: We started implementing the following SOAP-Methods, to achieve the requested feature:

  • getNewMailCount(sid[, folderid])returns the number of unread mails.
  • getMailCount(sid[, folderid])returns the number of mails.
  • getMailboxList(sid)returns a list of available directories (e.g. sent mails, inbox etc. )
  • getMails(sid, folderid[, flagNew][,lowerBound[,upperBound]]])returns a list with meta information about the mails within a folder. It should be possible to just retrieved unread mails, or to limit the time period in which the mails were received.
  • getMailContent(sid, mailid)returns the mail with all associated values.
  • setMailViewed(sid, mailid, isViewed)Offers the possibility to set the status of a mail as read or unread.
  • getAttachmentIDs(sid, mailid)returns the IDs of the files that are attached to the mail.
Does this match the feature request? Would it be possible to use our implementation? If not, what needs to be changed in order to do so?

Marcel Höll, 15. Dez 2014: Your suggested feature implementation:
 
 
The mentioned methods would be very nice. If you can implement that, please do so. Thank you in advance.

Martin Pelke, 19. Feb. 2015: I added our current implementation in the implementation section below. Today, we discovered that i might be necessary to implement a additional sendMessage() method, to be able to send messages within ilias over webservices.

Matthias Kunkel, 28 Feb 2015: This  feature was already scheduled for a previous ILIAS version but not merged into trunk due to missing funding or time. We re-schedule it automatically for 5.1 to save time for discussing new feature requests.

Zenzen, Enrico [ezenzen], 18 AUG 2022: This request no longer fulfills the requirements of the Feature Wiki. In consultation with the maintainer I change the status of the feature request to "Redundant / outdated". If the request is still relevant, please update template and mockups.

4 Implementation

The above mentioned methods are currently implemented as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
/**
     * Gibt die anzahl ungelesener Mails zur�ck
     *
     * @param $sid UserID
     * @return Anzahl ungelesener Mails
     */
    function getMailCount($sid, $folder_id, $only_new)
    {
        if (strlen ( $sid ) == 0)
        {
            return $this->__raiseError ( 'No sessionID got. Aborting', 'Client' );
        }
        if (strlen ( $folder_id ) == 0)
        {
            $folder_id = null;
        }
        if ($only_new === true || $only_new == 1 || strtolower ( $only_new ) == "true")
        {
            $only_new = true;
        }
        else
        {
            $only_new = false;
        }
 
        $this->initAuth ( $sid );
        $this->initIlias ();
 
        if (! $this->__checkSession ( $sid ))
        {
            return $this->__raiseError ( $this->__getMessage (), $this->__getMessageCode () );
        }
 
        global $ilUser;
 
        include_once 'Services/Mail/classes/class.ilAppHSWMailGlobalServices.php';
        return ilAppHSWMailGlobalServices::getNumberOfMailsByUserId ( $ilUser->getId (), $folder_id, $only_new );
    }
 
    /**
     * Listet alle Ordner der Mailbox des Benutzers auf
     *
     * @param $sid UserID
     * @return Liste aller Ordner (wie Posteingang, Papierkorb...)
     */
    function getMailboxlist($sid)
    {
        if (strlen ( $sid ) == 0)
        {
            return $this->__raiseError ( 'No sessionID got. Aborting', 'Client' );
        }
 
        $this->initAuth ( $sid );
        $this->initIlias ();
 
        if (! $this->__checkSession ( $sid ))
        {
            return $this->__raiseError ( $this->__getMessage (), $this->__getMessageCode () );
        }
 
        global $ilUser;
        include_once 'Services/Mail/classes/class.ilMailbox.php';
        $mbox = new ilMailBox ( $ilUser->getId () );
        $mailboxen = null;
        foreach ( $mbox->getSubFolders () as $folder )
        {
            $temp ['title'] = $folder ['title'];
            $temp ['type'] = $folder ['type'];
            $temp ['id'] = $folder ['obj_id'];
            $mailboxen [] = $temp;
        }
        return $mailboxen;
    }
 
    /**
     * Gibt eine Liste aller Mails zur�ck (nur Kopfinformationen: id, Titel, Sender, sendzeit, gelesen)
     *
     * @param $sid UserID
     * @param $folder_id OrdenerID
     * @param $von Start
     *            der Liste (optional)
     * @param $bis Ende
     *            der Liste (optional)
     * @param $only_new nur
     *            ungelesenen Mails (optional)
     * @return Mailliste
     */
    function getMails($sid, $folder_id, $von, $bis, $only_new)
    {
        // optional args
        if (strlen ( $von ) == 0)
        {
            $von = 0;
        }
        if ($only_new === true || $only_new == 1 || strtolower ( $only_new ) == "true")
        {
            $only_new = true;
        }
        else
        {
            $only_new = false;
        }
        // check argument
        if (strlen ( $sid ) == 0)
        {
            return $this->__raiseError ( 'No sessionID got. Aborting', 'Client' );
        }
        if (strlen ( $folder_id ) == 0)
        {
            return $this->__raiseError ( 'No folderID got. Aborting', 'Client' );
        }
        if (! is_numeric ( $von ))
        {
            return $this->__raiseError ( 'Startposition of maillist must be numerical: ' . $von . '. Aborting', 'Client' );
        }
        if (strlen ( $bis ) != 0 && ! is_numeric ( $bis ))
        {
            return $this->__raiseError ( 'Endposition of maillist must be numerical: ' . $bis . '. Aborting', 'Client' );
        }
        // validate
        if ($von < 1)
        {
            $von = 1;
        }
 
        $von --; // cause arrays starts on 0
 
        $this->initAuth ( $sid );
        $this->initIlias ();
        if (! $this->__checkSession ( $sid ))
        {
            return $this->__raiseError ( $this->__getMessage (), $this->__getMessageCode () );
        }
 
        global $ilUser;
 
        include_once 'Services/Mail/classes/class.ilMail.php';
        $mailhandler = new ilMail ( $ilUser->getId () );
 
        $mails_out = null;
        $mails = $mailhandler->getMailsOfFolder ( $folder_id );
        $mailcount = count ( $mails );
        if (strlen ( $bis ) == 0 || $bis > $mailcount)
        {
            $bis = $mailcount;
        }
        for($i = $von; $i <= $bis; $i ++)
        {
            $mail = $mails [$i];
            $temp ['isreaded'] = $mail ['m_status'] == 'read' ? true : false;
            if ($only_new === true && $temp ['isreaded'])
            {
                continue;
            }
            $sender = ilObjUser::_lookupName ( $mail ['sender_id'] );
            if ($sender)
            {
                $temp ['author_firstname'] = $sender ['firstname'];
                $temp ['author_lastname'] = $sender ['lastname'];
            }
            else
            {
                $temp ['author_firstname'] = null;
                $temp ['author_lastname'] = null;
            }
            $temp ['id'] = $mail ['mail_id'];
            $temp ['title'] = $mail ['m_subject'];
            $temp ['send_time'] = $mail ['send_time'];
            // for more informations musst call an other function as getMailsOfFolder
            $mails_out [] = $temp;
        }
        return ! isset ( $mails_out ) ? null : $mails_out;
    }
 
    /**
     * Liest Daten �ber der Mail aus und gibt diese zur�ck
     *
     * @param $sid UserID
     * @param $mail_id MailID
     * @return Maildaten
     */
    function readMail($sid, $mail_id)
    {
        if (strlen ( $sid ) == 0)
        {
            return $this->__raiseError ( 'No sessionID got. Aborting', 'Client' );
        }
        if (strlen ( $mail_id ) == 0 || !is_numeric($mail_id))
        {
            return $this->__raiseError ( 'No valid MailID got (MailID must be numeric). Aborting', 'Client' );
        }
 
        $this->initAuth ( $sid );
        $this->initIlias ();
        if (! $this->__checkSession ( $sid ))
        {
            return $this->__raiseError ( $this->__getMessage (), $this->__getMessageCode () );
        }
        global $ilUser;
 
        include_once 'Services/Mail/classes/class.ilMail.php';
        $mailhandler = new ilMail ( $ilUser->getId () );
 
        $mail = $mailhandler->getMail ( $mail_id );
        if (is_null($mail))
        {
             return $this->__raiseError ( 'User has no Mail with the given ID. Aborting', 'Client' );
        }
        $temp['sender_id'] = $mail['sender_id'];
        $sender = ilObjUser::_lookupName ( $mail ['sender_id'] );
        if ($sender)
        {
            $temp ['sender_firstname'] = $sender ['firstname'];
            $temp ['sender_lastname'] = $sender ['lastname'];
        }
        else
        {
            $temp ['sender_firstname'] = null;
            $temp ['sender_lastname'] = null;
        }
        $temp['betreff'] = $mail['m_subject'];
        $temp['send_time'] = $mail['send_time'];
        $temp['to'] = $mail['rcp_to'];
        $temp['cc'] = $mail['rcp_cc'];
        $temp['bcc'] = $mail['rcp_bcc'];
        $temp['inhalt'] = $mail['m_message'];
        $temp['isreaded'] = $mail['m_status'] == "read" ? true : false;
        $temp['attachments'] = $mail['attachments'];
 
        return $temp;
    }
 
    /**
     *
     * @param
     *            $sid
     * @param $mail_ids Array
     *            of Mailids (separatet with commas) to be marked
     * @param $readed Mails
     *            marked as reded? (optional, default: true)
     */
    function setMailViewed($sid, $mail_ids, $readed)
    {
        if (strlen ( $sid ) == 0)
        {
            return $this->__raiseError ( 'No sessionID got. Aborting', 'Client' );
        }
        if ($readed === true || strlen ( $readed ) == 0 || strtolower ( $readed ) == "true" || $readed == 1)
        {
            $readed = true;
        }
        else
        {
            $readed = false;
        }
        $mailIds = array ();
        foreach ( explode ( ",", $mail_ids ) as $mail_id )
        {
            if (! is_numeric ( trim ( $mail_id ) ))
            {
                continue;
            }
            $mailIds [] = $mail_id;
        }
 
        $this->initAuth ( $sid );
        $this->initIlias ();
 
        if (! $this->__checkSession ( $sid ))
        {
            return $this->__raiseError ( $this->__getMessage (), $this->__getMessageCode () );
        }
 
        global $ilUser;
        include_once 'Services/Mail/classes/class.ilMail.php';
        $mailhandler = new ilMail ( $ilUser->getId () );
        if ($readed)
        {
            $mailhandler->markRead ( $mailIds );
            return true;
        }
        else
        {
            $mailhandler->markUnread ( $mailIds );
            return true;
        }
    }

Last edited: 18. Aug 2022, 09:05, Zenzen, Enrico [ezenzen]