source: release-kits/lirk3/bin/ant-installer/web/manual1.7.0/manual/CoreTasks/mail.html@ 14982

Last change on this file since 14982 was 14982, checked in by oranfry, 16 years ago

initial import of LiRK3
File size: 11.4 KB
Line 
1<!--
2 Licensed to the Apache Software Foundation (ASF) under one or more
3 contributor license agreements. See the NOTICE file distributed with
4 this work for additional information regarding copyright ownership.
5 The ASF licenses this file to You under the Apache License, Version 2.0
6 (the "License"); you may not use this file except in compliance with
7 the License. You may obtain a copy of the License at
8
9 http://www.apache.org/licenses/LICENSE-2.0
10
11 Unless required by applicable law or agreed to in writing, software
12 distributed under the License is distributed on an "AS IS" BASIS,
13 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 See the License for the specific language governing permissions and
15 limitations under the License.
16-->
17<html>
18
19<head>
20<meta http-equiv="Content-Language" content="en-us">
21<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
22<title>Mail Task</title>
23</head>
24
25<body>
26
27<h2><a name="mail">Mail</a></h2>
28<h3>Description</h3>
29 <p>
30 A task to send SMTP email.
31 </p>
32 <p>
33 This task can send mail using either plain
34 text, UU encoding, or MIME format mail, depending on what is available.
35 </p>
36 <p>
37 SMTP auth and SSL/TLS require JavaMail and are only available in MIME format.
38 </p>
39 <p>
40 Attachments may be sent using nested
41 <code>&lt;attachments&gt;</code> elements, which are <a
42 href="../using.html#path">path-like structures</a>. This means
43 any filesystem based <a
44 href="../CoreTypes/resources.html">resource</a> or resource
45 collection can be used to point to attachments. Prior to Ant 1.7
46 only <code>&lt;fileset&gt;</code> has been supported as a nested
47 element, you can still use this directly without an
48 <code>&lt;attachments&gt;</code> container.
49 </p>
50 <p>
51 <strong>Note:</strong> This task may depend on external libraries
52 that are not included in the Ant distribution.
53 See <a href="../install.html#librarydependencies">Library Dependencies</a>
54 for more information.
55 </p>
56
57<h3>Parameters</h3>
58<table border="1" cellpadding="2" cellspacing="0">
59 <tr>
60 <td valign="top"><b>Attribute</b></td>
61 <td valign="top"><b>Description</b></td>
62 <td align="center" valign="top"><b>Required</b></td>
63 </tr>
64 <tr>
65 <td valign="top">from</td>
66 <td valign="top">Email address of sender.</td>
67 <td align="center" valign="top">Either a <code>from</code> attribute, or a <code>&lt;from&gt;</code>
68 element.</td>
69 </tr>
70 <tr>
71 <td valign="top">replyto</td>
72 <td valign="top">Replyto email address.</td>
73 <td align="center" valign="top">No</td>
74 </tr>
75 <tr>
76 <td valign="top">tolist</td>
77 <td valign="top">Comma-separated list of recipients.</td>
78 <td align="center" valign="middle" rowspan="3">At least one of these, or the
79 equivalent elements.</td>
80 </tr>
81 <tr>
82 <td valign="top">cclist</td>
83 <td valign="top">Comma-separated list of recipients to carbon copy</td>
84 </tr>
85 <tr>
86 <td valign="top">bcclist</td>
87 <td valign="top">Comma-separated list of recipients to blind carbon copy
88 </td>
89 </tr>
90 <tr>
91 <td valign="top">message</td>
92 <td valign="top">Message to send in the body of the email.</td>
93 <td align="center" valign="middle" rowspan="2">One of these or a
94 <code>&lt;message&gt;</code> element.</td>
95 </tr>
96 <tr>
97 <td valign="top">messagefile</td>
98 <td valign="top">File to send as the body of the email. Property
99 values in the file will be expanded.</td>
100 </tr>
101 <td valign="top">messagemimetype</td>
102 <td valign="top">The content type of the message. The default is
103 <code>text/plain</code>.</td>
104 <td align="center" valign="top">No</td>
105 </tr>
106 <tr>
107 <td valign="top">files</td>
108 <td valign="top">Files to send as attachments to the email. Separate multiple
109 file names using a comma or space. You can also use <code>&lt;fileset&gt;</code>
110 elements to specify files.</td>
111 <td align="center" valign="top">No</td>
112 </tr>
113 <tr>
114 <td valign="top">failonerror</td>
115 <td valign="top">flag to indicate whether to halt the build on
116 any error. The default value is <code>true</code>.</td>
117 <td align="center" valign="top">No.</td>
118 </tr>
119 <tr>
120 <td valign="top">includefilenames</td>
121 <td valign="top">Include filename(s) before file contents.
122 Valid only when the <code>plain</code> encoding is used. The default
123 value is <code>false</code>.</td>
124 <td align="center" valign="top">No</td>
125 </tr>
126 <tr>
127 <td valign="top">mailhost</td>
128 <td valign="top">Host name of the SMTP server. The default value is
129 <code>localhost</code>.</td>
130 <td align="center" valign="top">No</td>
131 </tr>
132 <tr>
133 <td valign="top">mailport</td>
134 <td valign="top">TCP port of the SMTP server. The default value is 25.</td>
135 <td align="center" valign="top">No</td>
136 </tr>
137 <tr>
138 <td valign="top">user</td>
139 <td valign="top">user name for SMTP auth</td>
140 <td valign="center">Yes, if SMTP auth is required on your SMTP server<br></br>
141 the email message will be then sent using Mime and requires JavaMail</td>
142 </tr>
143 <tr>
144 <td valign="top">password</td>
145 <td valign="top">password for SMTP auth</td>
146 <td valign="center">Yes, if SMTP auth is required on your SMTP server<br></br>
147 the email message will be then sent using Mime and requires JavaMail</td>
148 </tr>
149 <tr>
150 <td valign="top">ssl</td>
151 <td valign="top">"true", "on" or "yes" accepted here<br></br>
152 indicates whether you need TLS/SSL</td>
153 <td valign="center">No</td>
154 </tr>
155 <tr>
156 <td valign="top">encoding</td>
157 <td valign="top">Specifies the encoding to use for the content of the email.
158 Values are <code>mime</code>, <code>uu</code>, <code>plain</code>, or
159 <code>auto</code>. The default value is <code>auto</code>.
160 <code>uu</code> or <code>plain</code> are not compatible with SMTP auth</td>
161 <td align="center" valign="top">No</td>
162 </tr>
163 <tr>
164 <td valign="top">charset</td>
165 <td valign="top">Character set of the email.<br>
166 You can also set the charset in the message nested element.<br>
167 These options are mutually exclusive.</td>
168 <td align="center" valign="top">No</td>
169 </tr>
170 <tr>
171 <td valign="top">subject</td>
172 <td valign="top">Email subject line.</td>
173 <td align="center" valign="top">No</td>
174 </tr>
175</table>
176
177<h3>Note regarding the attributes containing email addresses</h3>
178Since Ant 1.6, the attributes from, replyto, tolist, cclist, bcclist
179can contain email addresses of the form :
180<ul>
181<li>[email protected]</li>
182<li>name &lt;[email protected]&gt;</li>
183<li>&lt;[email protected]&gt; name</li>
184<li>(name) [email protected]</li>
185<li>[email protected] (name)</li>
186</ul>
187<p>You need to enter the angle brackets as XML entities
188<code>&amp;gt;</code> and <code>&amp;lt;</code>.</p>
189
190<h3>Parameters specified as nested elements</h3>
191
192<h4>to / cc / bcc / from/ replyto </h4>
193<p>Adds an email address element. It takes the following attributes:</p>
194
195<table width="60%" border="1" cellpadding="2" cellspacing="0">
196 <tr>
197 <td valign="top"><b>Attribute</b></td>
198 <td valign="top"><b>Description</b></td>
199 <td align="center" valign="top"><b>Required</b></td>
200 </tr>
201 <tr>
202 <td valign="top">name</td>
203 <td valign="top">The display name for the address.</td>
204 <td align="center" valign="top">No</td>
205 </tr>
206 <tr>
207 <td valign="top">address</td>
208 <td valign="top">The email address.</td>
209 <td align="center" valign="top">Yes</td>
210 </tr>
211</table>
212
213<h4>message</h4>
214
215<p>Specifies the message to include in the email body. It takes the following
216attributes:</p>
217
218<table width="60%" border="1" cellpadding="2" cellspacing="0">
219 <tr>
220 <td valign="top"><b>Attribute</b></td>
221 <td valign="top"><b>Description</b></td>
222 <td align="center" valign="top"><b>Required</b></td>
223 </tr>
224 <tr>
225 <td valign="top">src</td>
226 <td valign="top">The file to use as the message.</td>
227 <td align="center" valign="top">No</td>
228 </tr>
229 <tr>
230 <td valign="top">mimetype</td>
231 <td valign="top">The content type to use for the message.</td>
232 <td align="center" valign="top">No</td>
233 </tr>
234 <tr>
235 <td valign="top">charset</td>
236 <td valign="top">Character set of the message<br>
237 You can also set the charset as attribute of the enclosing mail task.<br>
238 These options are mutually exclusive.</td>
239 <td align="center" valign="top">No</td>
240 </tr>
241</table>
242
243<p>If the <code>src</code> attribute is not specified, then text can be added
244inside the <code>&lt;message&gt;</code> element. Property expansion will occur
245in the message, whether it is specified as an external file or as text within
246the <code>&lt;message&gt;</code> element.</p>
247
248<h4>header</h4>
249<p><strong>Since Ant 1.7</strong>, arbitrary mail headers can be added by
250 specifying these attributes on one or more nested header elements:</p>
251
252<table width="60%" border="1" cellpadding="2" cellspacing="0">
253 <tr>
254 <td valign="top"><b>Attribute</b></td>
255 <td valign="top"><b>Description</b></td>
256 <td align="center" valign="top"><b>Required</b></td>
257 </tr>
258 <tr>
259 <td valign="top">name</td>
260 <td valign="top">The name associated with this mail header.</td>
261 <td align="center" valign="top">Yes</td>
262 </tr>
263 <tr>
264 <td valign="top">value</td>
265 <td valign="top">The value to assign to this mail header.</td>
266 <td align="center" valign="top">Yes</td>
267 </tr>
268</table>
269
270<p>It is permissible to duplicate the name attribute amongst multiple headers.
271</p>
272
273<h3>Examples</h3>
274
275<blockquote><pre>
276&lt;mail from=&quot;me&quot;
277 tolist=&quot;you&quot;
278 subject=&quot;Results of nightly build&quot;
279 files=&quot;build.log&quot;/&gt;
280</pre></blockquote>
281
282<p>Sends an email from <i>me</i> to <i>you</i> with a subject of
283<i>Results of nightly build</i> and includes the contents of the file
284<i>build.log</i> in the body of the message.</p>
285
286<blockquote><pre>
287&lt;mail mailhost=&quot;smtp.myisp.com&quot; mailport=&quot;1025&quot; subject=&quot;Test build&quot;&gt;
288 &lt;from address=&quot;[email protected]&quot;/&gt;
289 &lt;replyto address=&quot;[email protected]&quot;/&gt;
290 &lt;to address=&quot;[email protected]&quot;/&gt;
291 &lt;message&gt;The ${buildname} nightly build has completed&lt;/message&gt;
292 &lt;attachments&gt;
293 &lt;fileset dir=&quot;dist&quot;&gt;
294 &lt;include name=&quot;**/*.zip&quot;/&gt;
295 &lt;/fileset&gt;
296 &lt;/attachments&gt;
297&lt;/mail&gt;
298</pre></blockquote>
299
300<p>Sends an eMail from <i>[email protected]</i> to <i>[email protected]</i> with a subject of
301<i>Test Build</i>. Replies to this email will go to <i>[email protected]</i>.
302Any zip files from the dist directory are attached.&nbsp; The
303task will attempt to use JavaMail and fall back to UU encoding or no encoding in
304that order depending on what support classes are available. <code>${buildname}</code>
305will be replaced with the <code>buildname</code> property's value.</p>
306
307<blockquote><pre>
308&lt;property name=&quot;line2&quot; value=&quot;some_international_message&quot;/&gt;
309&lt;echo message=&quot;${line2}&quot;/&gt;
310
311&lt;mail mailhost=&quot;[email protected]&quot; mailport=&quot;25&quot; subject=&quot;Test build&quot; charset=&quot;utf-8&quot;&gt;
312 &lt;from address=&quot;[email protected]&quot;/&gt;
313 &lt;to address=&quot;[email protected]&quot;/&gt;
314 &lt;message&gt;some international text:${line2}&lt;/message&gt;
315&lt;/mail&gt;
316</pre></blockquote>
317
318<p>Sends an eMail from <i>[email protected]</i> to <i>[email protected]</i> with a subject of
319<i>Test Build</i>, the message body being coded in UTF-8
320
321
322
323</body>
324</html>
Note: See TracBrowser for help on using the repository browser.