Changes for page Mail Sender API

Last modified by Vincent Massol on 2017/10/06 13:49

From version 49.11
edited by Admin
on 2017/10/05 15:13
To version 50.1
edited by Vincent Massol
on 2017/10/06 13:49
Change comment: There is no comment for this version

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -xwiki:XWiki.Admin
1 +xwiki:XWiki.VincentMassol
ExtensionCode.ExtensionClass[0]
Description
... ... @@ -3,6 +3,7 @@
3 3  {{/info}}
4 4  
5 5  This API allows to:
6 +
6 6  * Ability to send Multipart emails with any type of mime type content (html, text, vcalendar, etc)
7 7  * Ability to embed images in HTML emails
8 8  * Ability to send mail templates
... ... @@ -19,6 +19,7 @@
19 19  
20 20  Most API examples below are written in Velocity. If you're using this module from Java make sure to check the [[Java API Example>>||anchor="HUsingfromJava"]] below.
21 21  
23 +
22 22  == Create a Message ==
23 23  
24 24  {{code language="none"}}
... ... @@ -36,7 +36,9 @@
36 36  
37 37  == Add Content ==
38 38  
39 -{{info}}The first parameter is a Mime Type and it corresponds to a [[Component Hint for a ##MimeBodyPartFactory##>>||anchor="HMimeBodyPartFactoryImplementations"]]{{/info}}
41 +{{info}}
42 +The first parameter is a Mime Type and it corresponds to a [[Component Hint for a ##MimeBodyPartFactory##>>||anchor="HMimeBodyPartFactoryImplementations"]]
43 +{{/info}}
40 40  
41 41  * Add Simple text:(((
42 42  {{code language="none"}}
... ... @@ -68,10 +68,10 @@
68 68  $message.addPart("xwiki/template", $documentReference, {"velocityVariables" : { "var1" : "value1" }})
69 69  {{/code}}
70 70  )))
71 -* Same as previous addPart() example but also add internationalization support by retrieving the ##XWiki.Mail## Object which has a ##language## property equals to ##fr##(((
72 -{{code language="none"}}
75 +* Same as previous addPart() example but also add internationalization support by retrieving the ##XWiki.Mail## Object which has a ##language## property equals to (((
76 +fr##{{code language="none"}}
73 73  $message.addPart("xwiki/template", $documentReference, {"language" : "fr", "velocityVariables" : { "var1" : "value1" }})
74 -{{/code}}
78 +{{/code}}##
75 75  )))
76 76  * Add HTML + alternate text + embedded images + some attachments, from a Template Document containing a ##XWiki.Mail## object. Any ##$var1## Velocity variable is replaced with ##value1##. (Note: ##$attachments## is of type ##List<Attachment>## here).(((
77 77  {{code language="none"}}
... ... @@ -122,8 +122,9 @@
122 122  
123 123  == Check Message Statuses ==
124 124  
125 -When mails are sent asynchronously it's possible to check the status of the sending process by calling:(((
129 +When mails are sent asynchronously it's possible to check the status of the sending process by calling:
126 126  
131 +(((
127 127  {{info}}XWiki 7.1+{{/info}}:
128 128  
129 129  {{code language="none"}}
... ... @@ -157,6 +157,7 @@
157 157  {{/code}}
158 158  
159 159  This can happen for example under the following conditions:
165 +
160 160  * If an error happened when creating the message(s) (when using the ##$services.mailsender.createMessage(...)## APIs)
161 161  * If there isn't enough permission to send mail (for example if the page containing the sending script doesn't have Programming Rights)
162 162  * If the Mail Listener referenced by the second parameter of ##$services.mailsender.send(messages, mailListenerHint)## doesn't exist
... ... @@ -239,7 +239,9 @@
239 239  
240 240  == Accessing Configuration ==
241 241  
242 -Access the Mail Sending configuration. In this example we define a default from email address if no from is defined on the configuration:(((
248 +Access the Mail Sending configuration. In this example we define a default from email address if no from is defined on the configuration:
249 +
250 +(((
243 243  {{code language="none"}}
244 244  #set ($from = $services.mailsender.configuration.fromAddress)
245 245  #if ("$!from" == '')
... ... @@ -251,11 +251,13 @@
251 251  == MimeBodyPartFactory Implementations ==
252 252  
253 253  When adding a body part using the ##addPart(mimeType, source, ...)## script API, the following logic is used:
262 +
254 254  * Look for a Component implementing ##MimeBodyPartFactory## and using the passed ##mimeType## as a Hint.
255 255  * If no Component is found and the ##source## is a String then defaults to using the ##default## ##MimeBodyPartFactory## implementation
256 256  * Otherwise throws an exception.
257 257  
258 258  The following implementations are available:
268 +
259 259  * ##default##: Creates a text Message Body Part.
260 260  * ##text/html##: Creates an HTML BodyPart that supports a text alternative and a list of attachments that will be added to the mail as standard attachments and also as embedded images if they are referenced in the passed HTML using the format {{code language="none"}}<img src="cid:(attachment name)"/>{{/code}}.
261 261  * ##xwiki/attachment##: Creates an attachment Body Part from an ##Attachment## object.
... ... @@ -263,7 +263,9 @@
263 263  
264 264  == Specialized Message Factories ==
265 265  
266 -There are also specialized Message factories that can be used to create pre-filled Message objects. For example it's possible to create a message having its subject automatically computed from a template (i.e. from a wiki page having a ##XWiki.Mail## object), by evaluating its ##subject## xproperty with Velocity (see the example further below for more details) + having a template body part added too. Generic API:(((
276 +There are also specialized Message factories that can be used to create pre-filled Message objects. For example it's possible to create a message having its subject automatically computed from a template (i.e. from a wiki page having a ##XWiki.Mail## object), by evaluating its ##subject## xproperty with Velocity (see the example further below for more details) + having a template body part added too. Generic API:
277 +
278 +(((
267 267  {{code language="none"}}
268 268  #set ($message = $services.mailsender.createMessage(hint, source, parameters))
269 269  #set ($messages = $services.mailsender.createMessages(hint, source, parameters))
... ... @@ -270,6 +270,7 @@
270 270  {{/code}}
271 271  
272 272  Where:
285 +
273 273  * ##hint## is the Component hint of the component implementing the ##org.xwiki.mail.MimeMessageFactory## role.
274 274  * ##source## depends on the hint used. For example when the hint is ##template##, the source represents the Document Reference to a page containing an ##XWiki.Mail## object.
275 275  * ##parameters## depends on the hint used too. For example when the hint is ##template##, it's used to pass Velocity variables and values to use when evaluating the ##subject## xproperty of the ##XWiki.Mail## object.
... ... @@ -322,7 +322,7 @@
322 322  result.getStatusResult().waitTillProcessed(10000L);
323 323  {{/code}}
324 324  
325 -=== Get standard Session
338 +=== Get standard Session ===
326 326  
327 327  Since 8.3 it's also possible to directly create a pre-configured mail ##Session##.
328 328  
... ... @@ -492,6 +492,29 @@
492 492  #set ($source = {'groups' : [$groupReference], 'users' : [$user1Reference, $user2Reference], 'emails' : ['[email protected]'], 'excludedUsers' : [], 'excludedEmails' : [], 'excludedGroups' : []})
493 493  {{/code}}
494 494  
508 +To try this out, here's a script that sends some mail to all registered users of a wiki. To use it, create a ##Admin.MailTemplate## terminal page and add a ##XWiki.Mail## xobject to it and put the following content in any page:
509 +
510 +{{code language="velocity"}}
511 +{{velocity}}
512 +#if ("$!request.confirm" == '1')
513 + #set ($templateParameters = {'type' : 'SendAll', 'language' : $xcontext.language })
514 + #set ($templateReference = $services.model.createDocumentReference('', 'Admin', 'MailTemplate'))
515 + #set ($parameters = {'hint' : 'template', 'parameters' : $templateParameters, 'source' : $templateReference })
516 +
517 + #set ($groupReference = $services.model.createDocumentReference('', 'XWiki', 'XWikiAllGroup'))
518 + #set ($source = {'groups' : [$groupReference]})
519 +
520 + #set ($messages = $services.mailsender.createMessages('usersandgroups', $source, $parameters))
521 +
522 + #set ($mailResult = $services.mailsender.send($messages, 'database'))
523 +
524 + Mails are being sent. Check the status in the [[Admin>>path:$xwiki.getURL('XWiki.XWikiPreferences', 'admin', 'editor=globaladmin&section=emailStatus')]].
525 +#else
526 + To send email to all users, [[click here>>||queryString='confirm=1']]
527 +#end
528 +{{/velocity}}
529 +{{/code}}
530 +
495 495  == Example 5: Send a prepared Mime Message to a list of Users and Groups ==
496 496  
497 497  {{info}}XWiki 7.1{{/info}} The following example is similar to the previous one, except that it use a fixed prepared mime message to send it to multiple users as separate independent message. (ie: all the users in the ##XWiki.MyGroup## group).
... ... @@ -515,6 +515,7 @@
515 515  = Configuration =
516 516  
517 517  Mail Sender configuration properties are searched in various places, using the following order:
554 +
518 518  * Look for a non-empty value in ##Mail.MailConfig## in the current wiki
519 519  * [Backward compatibility] Look for a non-empty value in ##(current space).XWikiPreferences## in the current wiki
520 520  * [Backward compatibility] Look for a non-empty value in in ##XWiki.XWikiPreferences## in the current wiki
... ... @@ -529,6 +529,7 @@
529 529  = Extending =
530 530  
531 531  There are 2 ways to extend the API:
569 +
532 532  * By implementing components that implement the ##MimeBodyPartFactory## role.
533 533  * By implementing components that implement the ##MimeMessageFactory## role.
534 534  
... ... @@ -619,3 +619,5 @@
619 619  {{jira url="https://jira.xwiki.org" fields="type, key, status, summary, assignee" source="jql"}}
620 620  project = "XWiki Platform" and resolution = Unresolved and component = Mail
621 621  {{/jira}}
660 +)))
661 +)))

Get Connected