69946bea50f16f7d66ec5552d157be88842f5209
[asterisk/asterisk.git] / doc / imapstorage.txt
1 ======================
2 IMAP Voicemail Storage
3 ======================
4
5 03-01-2006 - James Rothenberger <jar@onebiztone.com>
6
7 By enabling IMAP Storage,  Asterisk will use native IMAP as the storage
8 mechanism for voicemail messages instead of using the standard file structure.
9
10 Tighter integration of Asterisk voicemail and IMAP email services allows
11 additional voicemail functionality, including:
12
13  - Listening to a voicemail on the phone will set its state to "read" in
14    a user's mailbox automatically.
15  - Deleting a voicemail on the phone will delete it from the user's
16    mailbox automatically.
17  - Accessing a voicemail recording email message will turn off the message
18    waiting indicator (MWI) on the user's phone.
19  - Deleting a voicemail recording email will also turn off the message 
20    waiting indicator, and delete the message from the voicemail system.
21
22 =====================
23 Contents of this file
24 =====================
25
26  - Installation Notes
27  - Separate vs. Shared Email Accounts
28  - IMAP Server Implementations
29  - Quota Support
30  - Application Notes
31  - Known Issues
32
33
34 ==================
35 Installation Notes
36 ==================
37
38 --------------------------------------
39 University of Washington IMAP C-Client
40 --------------------------------------
41 You will need a source distribution of University of Washington's IMAP
42 c-client (http://www.washington.edu/imap/).  Asterisk supports both the
43 2004 and 2006 versions of c-client, however mail_expunge_full is enabled
44 in the 2006 version.  You will want to make the appropriate changes 
45 to the c-client Makefile, for instance:
46
47 EXTRAAUTHENTICATORS=gss
48 EXTRADRIVERS=mbox
49
50 In src/osdep/unix/Makefile, set CREATEPROTO to mbxproto.  This is done
51 to utilize mbx mailbox format (see below).
52
53 Compile c-client and verify that a c-client.a file has been generated.
54
55 ------------------
56 Compiling Asterisk 
57 ------------------
58
59 Configure with ./configure --with-imap=/usr/src/imap
60 or where ever you built the University of Washington IMAP C-Client.
61 Then make menuselect go to voicemail options and check the imap box
62 then make, make install and asterisk will have imap storage support for 
63 voicemail. 
64
65 ---------------------
66 Modify voicemail.conf
67 ---------------------
68 The following directives have been added to voicemail.conf:
69
70 imapserver=<name or IP address of IMAP mail server>
71 imapport=<IMAP port, defaults to 143>
72 imapflags=<IMAP flags, "novalidate-cert" for example>
73 expungeonhangup=<yes or no>
74 authuser=<username>
75 authpassword=<password>
76
77 The "expungeonhangup" flag is used to determine if the voicemail system should
78 expunge all messages marked for deletion when the user hangs up the phone. 
79
80 Each mailbox definition should also have imapuser=<imap username>.
81 For example:
82
83 4123=>4123,James Rothenberger,jar@onebiztone.com,,attach=yes|imapuser=jar
84
85 The directives "authuser" and "authpassword" are not needed when using
86 Kerberos. They are defined to allow Asterisk to authenticate as a single 
87 user that has access to all mailboxes as an alternative to Kerberos.
88
89 --------------
90 Mailbox Format
91 --------------
92 Mailboxes should use the "mbx" mailbox format.  The "mbox" format does not
93 support concurrent access to mailboxes, which can cause deadlock or strange
94 behaviors. You can convert mailboxes from mbox to mbx using mailutil:
95
96 mailutil copy INBOX #driver.mbx/INBOX
97
98 --------------
99 IMAP Folders
100 --------------
101 Besides INBOX, users should create "Old", "Work", "Family" and "Friends" 
102 IMAP folders at the same level of hierarchy as the INBOX.  These will be 
103 used as alternate folders for storing voicemail messages to mimic the 
104 behavior of the current (file-based) voicemail system.
105
106
107 ==================================
108 Separate vs. Shared Email Accounts
109 ==================================
110 As administrator you will have to decide if you want to send the voicemail
111 messages to a separate IMAP account or use each user's existing IMAP mailbox
112 for voicemail storage.  The IMAP storage mechanism will work either way. 
113
114 By implementing a single IMAP mailbox, the user will see voicemail messages
115 appear in the same INBOX as other messages.  The disadvantage of this method
116 is that if the IMAP server does NOT support UIDPLUS, Asterisk voicemail will
117 expunge ALL messages marked for deletion when the user exits the voicemail 
118 system, not just the VOICEMAIL messages marked for deletion.
119
120 By implementing separate IMAP mailboxes for voicemail and email, voicemail 
121 expunges will not remove regular email flagged for deletion.
122
123 ===========================
124 IMAP Server Implementations
125 ===========================
126 There are various IMAP server implementations, each supports a potentially
127 different set of features.  
128
129 -----------------------
130 UW IMAP-2005 or earlier
131 -----------------------
132 UIDPLUS is currently NOT supported on these versions of UW-IMAP.  Please note
133 that without UID_EXPUNGE, Asterisk voicemail will expunge ALL messages marked
134 for deletion when a user exits the voicemail system (hangs up the phone).
135
136 -------------------------------
137 UW IMAP-2006 Development Branch
138 -------------------------------
139 This version supports UIDPLUS, which allows UID_EXPUNGE capabilities.  This
140 feature allow the system to expunge ONLY pertinent messages, instead of the
141 default behavior, which is to expunge ALL messages marked for deletion when
142 EXPUNGE is called.  The IMAP storage mechanism is this version of Asterisk
143 will check if the UID_EXPUNGE feature is supported by the server, and use it
144 if possible. 
145
146 ----------
147 Cyrus IMAP
148 ----------
149 Cyrus IMAP server v2.3.3 has been tested using a hierarchy delimiter of '/'.  
150
151
152 =============
153 Quota Support
154 =============
155 If the IMAP server supports quotas, Asterisk will check the quota when
156 accessing voicemail.  Currently only a warning is given to the user that 
157 their quota is exceeded. 
158
159
160 =================
161 Application Notes
162 =================
163 Since the primary storage mechanism is IMAP, all message information that 
164 was previously stored in an associated text file, AND the recording itself,
165 is now stored in a single email message.  This means that the .gsm recording
166 will ALWAYS be attached to the message (along with the user's preference of
167 recording format if different - ie. .WAV).  The voicemail message information
168 is stored in the email message headers.  These headers include:
169
170 X-Asterisk-VM-Message-Num
171 X-Asterisk-VM-Server-Name
172 X-Asterisk-VM-Context
173 X-Asterisk-VM-Extension
174 X-Asterisk-VM-Priority
175 X-Asterisk-VM-Caller-channel
176 X-Asterisk-VM-Caller-ID-Num
177 X-Asterisk-VM-Caller-ID-Name
178 X-Asterisk-VM-Duration
179 X-Asterisk-VM-Category
180 X-Asterisk-VM-Orig-date
181 X-Asterisk-VM-Orig-time
182
183 =================
184 Known Issues
185 =================
186
187  - Forward With Comment advanced option is not currently supported.
188    This feature will be added in the near future.
189  - Message Waiting Indicator blinks off and back on when a message arrives.
190    This should be fixed soon.