2006-09-11 04:19:00 +00:00
|
|
|
<!--
|
|
|
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
|
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
|
|
|
this work for additional information regarding copyright ownership.
|
|
|
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
|
|
|
(the "License"); you may not use this file except in compliance with
|
|
|
|
|
the License. You may obtain a copy of the License at
|
|
|
|
|
|
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
|
|
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
|
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
|
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
|
|
|
See the License for the specific language governing permissions and
|
|
|
|
|
limitations under the License.
|
|
|
|
|
-->
|
2001-02-13 12:32:01 +00:00
|
|
|
<html>
|
|
|
|
|
|
|
|
|
|
<head>
|
|
|
|
|
<meta http-equiv="Content-Language" content="en-us">
|
2005-04-29 18:58:16 +00:00
|
|
|
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
|
2002-02-03 22:00:42 +00:00
|
|
|
<title>Mail Task</title>
|
2001-02-13 12:32:01 +00:00
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
|
|
|
|
|
<h2><a name="mail">Mail</a></h2>
|
|
|
|
|
<h3>Description</h3>
|
2005-03-10 13:01:55 +00:00
|
|
|
<p>
|
|
|
|
|
A task to send SMTP email.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
This task can send mail using either plain
|
|
|
|
|
text, UU encoding, or MIME format mail, depending on what is available.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
SMTP auth and SSL/TLS require JavaMail and are only available in MIME format.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
Attachments may be sent using nested
|
2005-11-29 04:44:04 +00:00
|
|
|
<code><attachments></code> elements, which are <a
|
|
|
|
|
href="../using.html#path">path-like structures</a>. This means
|
|
|
|
|
any filesystem based <a
|
|
|
|
|
href="../CoreTypes/resources.html">resource</a> or resource
|
|
|
|
|
collection can be used to point to attachments. Prior to Ant 1.7
|
|
|
|
|
only <code><fileset></code> has been supported as a nested
|
|
|
|
|
element, you can still use this directly without an
|
|
|
|
|
<code><attachments></code> container.
|
2005-03-10 13:01:55 +00:00
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<strong>Note:</strong> This task may depend on external libraries
|
|
|
|
|
that are not included in the Ant distribution.
|
|
|
|
|
See <a href="../install.html#librarydependencies">Library Dependencies</a>
|
|
|
|
|
for more information.
|
|
|
|
|
</p>
|
2001-08-30 13:23:14 +00:00
|
|
|
|
2001-02-13 12:32:01 +00:00
|
|
|
<h3>Parameters</h3>
|
|
|
|
|
<table border="1" cellpadding="2" cellspacing="0">
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top"><b>Attribute</b></td>
|
|
|
|
|
<td valign="top"><b>Description</b></td>
|
|
|
|
|
<td align="center" valign="top"><b>Required</b></td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">from</td>
|
|
|
|
|
<td valign="top">Email address of sender.</td>
|
2002-02-05 09:32:48 +00:00
|
|
|
<td align="center" valign="top">Either a <code>from</code> attribute, or a <code><from></code>
|
|
|
|
|
element.</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
2003-05-15 11:30:27 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">replyto</td>
|
|
|
|
|
<td valign="top">Replyto email address.</td>
|
|
|
|
|
<td align="center" valign="top">No</td>
|
|
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">tolist</td>
|
|
|
|
|
<td valign="top">Comma-separated list of recipients.</td>
|
2002-02-05 09:32:48 +00:00
|
|
|
<td align="center" valign="middle" rowspan="3">At least one of these, or the
|
|
|
|
|
equivalent elements.</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">cclist</td>
|
|
|
|
|
<td valign="top">Comma-separated list of recipients to carbon copy</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">bcclist</td>
|
2005-11-16 19:43:32 +00:00
|
|
|
<td valign="top">Comma-separated list of recipients to blind carbon copy
|
|
|
|
|
</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">message</td>
|
|
|
|
|
<td valign="top">Message to send in the body of the email.</td>
|
2002-02-05 09:32:48 +00:00
|
|
|
<td align="center" valign="middle" rowspan="2">One of these or a
|
|
|
|
|
<code><message></code> element.</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">messagefile</td>
|
2002-06-22 23:38:38 +00:00
|
|
|
<td valign="top">File to send as the body of the email. Property
|
|
|
|
|
values in the file will be expanded.</td>
|
2002-02-05 09:32:48 +00:00
|
|
|
</tr>
|
|
|
|
|
<td valign="top">messagemimetype</td>
|
|
|
|
|
<td valign="top">The content type of the message. The default is
|
|
|
|
|
<code>text/plain</code>.</td>
|
|
|
|
|
<td align="center" valign="top">No</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">files</td>
|
2002-02-05 09:32:48 +00:00
|
|
|
<td valign="top">Files to send as attachments to the email. Separate multiple
|
2003-03-28 15:02:53 +00:00
|
|
|
file names using a comma or space. You can also use <code><fileset></code>
|
2002-02-05 09:32:48 +00:00
|
|
|
elements to specify files.</td>
|
|
|
|
|
<td align="center" valign="top">No</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
2002-01-02 05:16:41 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">failonerror</td>
|
2002-02-05 09:32:48 +00:00
|
|
|
<td valign="top">flag to indicate whether to halt the build on
|
|
|
|
|
any error. The default value is <code>true</code>.</td>
|
|
|
|
|
<td align="center" valign="top">No.</td>
|
|
|
|
|
</tr>
|
2001-12-10 18:01:16 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">includefilenames</td>
|
|
|
|
|
<td valign="top">Include filename(s) before file contents.
|
2002-02-05 09:32:48 +00:00
|
|
|
Valid only when the <code>plain</code> encoding is used. The default
|
|
|
|
|
value is <code>false</code>.</td>
|
|
|
|
|
<td align="center" valign="top">No</td>
|
2001-12-10 18:01:16 +00:00
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">mailhost</td>
|
2002-02-05 09:32:48 +00:00
|
|
|
<td valign="top">Host name of the SMTP server. The default value is
|
|
|
|
|
<code>localhost</code>.</td>
|
|
|
|
|
<td align="center" valign="top">No</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
2001-11-15 22:11:28 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">mailport</td>
|
2002-02-05 09:32:48 +00:00
|
|
|
<td valign="top">TCP port of the SMTP server. The default value is 25.</td>
|
|
|
|
|
<td align="center" valign="top">No</td>
|
|
|
|
|
</tr>
|
2003-05-27 15:33:25 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">user</td>
|
|
|
|
|
<td valign="top">user name for SMTP auth</td>
|
2003-12-23 15:57:02 +00:00
|
|
|
<td valign="center">Yes, if SMTP auth is required on your SMTP server<br></br>
|
2003-05-27 15:33:25 +00:00
|
|
|
the email message will be then sent using Mime and requires JavaMail</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">password</td>
|
|
|
|
|
<td valign="top">password for SMTP auth</td>
|
2003-12-23 15:57:02 +00:00
|
|
|
<td valign="center">Yes, if SMTP auth is required on your SMTP server<br></br>
|
2003-05-27 15:33:25 +00:00
|
|
|
the email message will be then sent using Mime and requires JavaMail</td>
|
|
|
|
|
</tr>
|
2003-05-28 20:58:03 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">ssl</td>
|
2003-12-23 15:57:02 +00:00
|
|
|
<td valign="top">"true", "on" or "yes" accepted here<br></br>
|
2003-05-28 20:58:03 +00:00
|
|
|
indicates whether you need TLS/SSL</td>
|
|
|
|
|
<td valign="center">No</td>
|
|
|
|
|
</tr>
|
2002-02-05 09:32:48 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">encoding</td>
|
|
|
|
|
<td valign="top">Specifies the encoding to use for the content of the email.
|
|
|
|
|
Values are <code>mime</code>, <code>uu</code>, <code>plain</code>, or
|
2003-05-27 15:33:25 +00:00
|
|
|
<code>auto</code>. The default value is <code>auto</code>.
|
|
|
|
|
<code>uu</code> or <code>plain</code> are not compatible with SMTP auth</td>
|
2002-02-05 09:32:48 +00:00
|
|
|
<td align="center" valign="top">No</td>
|
2001-11-15 22:11:28 +00:00
|
|
|
</tr>
|
2003-04-17 17:09:35 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">charset</td>
|
|
|
|
|
<td valign="top">Character set of the email.<br>
|
|
|
|
|
You can also set the charset in the message nested element.<br>
|
|
|
|
|
These options are mutually exclusive.</td>
|
|
|
|
|
<td align="center" valign="top">No</td>
|
|
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">subject</td>
|
|
|
|
|
<td valign="top">Email subject line.</td>
|
|
|
|
|
<td align="center" valign="top">No</td>
|
|
|
|
|
</tr>
|
2008-10-14 13:12:23 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">ignoreInvalidRecipients</td>
|
|
|
|
|
<td valign="top">Boolean. Whether the task should try to send
|
|
|
|
|
the message to as many recipients as possible and should only
|
|
|
|
|
fail if neither is reachable. <em>Since Ant 1.8.0</em>.</td>
|
|
|
|
|
<td align="center" valign="top">No, default is false</td>
|
|
|
|
|
</tr>
|
2008-10-23 13:13:36 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">enableStartTLS</td>
|
|
|
|
|
<td valign="top">"true", "on" or "yes" accepted here<br></br>
|
|
|
|
|
whether the STARTTLS command used to switch to an encrypted
|
|
|
|
|
connection for authentication should be supported. Requires
|
|
|
|
|
JavaMail. <em>Since Ant 1.8.0</em></td>
|
|
|
|
|
<td valign="center">No</td>
|
|
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
</table>
|
2002-02-05 09:32:48 +00:00
|
|
|
|
2003-08-19 12:15:04 +00:00
|
|
|
<h3>Note regarding the attributes containing email addresses</h3>
|
2006-07-24 16:16:42 +00:00
|
|
|
Since Ant 1.6, the attributes from, replyto, tolist, cclist, bcclist
|
2003-08-19 12:15:04 +00:00
|
|
|
can contain email addresses of the form :
|
|
|
|
|
<ul>
|
|
|
|
|
<li>address@xyz.com</li>
|
|
|
|
|
<li>name <address@xyz.com></li>
|
|
|
|
|
<li><address@xyz.com> name</li>
|
|
|
|
|
<li>(name) address@xyz.com</li>
|
|
|
|
|
<li>address@xyz.com (name)</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>You need to enter the angle brackets as XML entities
|
|
|
|
|
<code>&gt;</code> and <code>&lt;</code>.</p>
|
|
|
|
|
|
2002-02-05 09:32:48 +00:00
|
|
|
<h3>Parameters specified as nested elements</h3>
|
|
|
|
|
|
2003-05-15 11:30:27 +00:00
|
|
|
<h4>to / cc / bcc / from/ replyto </h4>
|
2002-02-05 09:32:48 +00:00
|
|
|
<p>Adds an email address element. It takes the following attributes:</p>
|
|
|
|
|
|
|
|
|
|
<table width="60%" border="1" cellpadding="2" cellspacing="0">
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top"><b>Attribute</b></td>
|
|
|
|
|
<td valign="top"><b>Description</b></td>
|
|
|
|
|
<td align="center" valign="top"><b>Required</b></td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">name</td>
|
|
|
|
|
<td valign="top">The display name for the address.</td>
|
|
|
|
|
<td align="center" valign="top">No</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">address</td>
|
|
|
|
|
<td valign="top">The email address.</td>
|
|
|
|
|
<td align="center" valign="top">Yes</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
<h4>message</h4>
|
|
|
|
|
|
|
|
|
|
<p>Specifies the message to include in the email body. It takes the following
|
|
|
|
|
attributes:</p>
|
|
|
|
|
|
|
|
|
|
<table width="60%" border="1" cellpadding="2" cellspacing="0">
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top"><b>Attribute</b></td>
|
|
|
|
|
<td valign="top"><b>Description</b></td>
|
|
|
|
|
<td align="center" valign="top"><b>Required</b></td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">src</td>
|
|
|
|
|
<td valign="top">The file to use as the message.</td>
|
|
|
|
|
<td align="center" valign="top">No</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">mimetype</td>
|
|
|
|
|
<td valign="top">The content type to use for the message.</td>
|
|
|
|
|
<td align="center" valign="top">No</td>
|
|
|
|
|
</tr>
|
2003-04-17 17:09:35 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">charset</td>
|
|
|
|
|
<td valign="top">Character set of the message<br>
|
|
|
|
|
You can also set the charset as attribute of the enclosing mail task.<br>
|
|
|
|
|
These options are mutually exclusive.</td>
|
|
|
|
|
<td align="center" valign="top">No</td>
|
|
|
|
|
</tr>
|
2002-02-05 09:32:48 +00:00
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
<p>If the <code>src</code> attribute is not specified, then text can be added
|
2002-06-22 23:38:38 +00:00
|
|
|
inside the <code><message></code> element. Property expansion will occur
|
|
|
|
|
in the message, whether it is specified as an external file or as text within
|
|
|
|
|
the <code><message></code> element.</p>
|
2002-02-05 09:32:48 +00:00
|
|
|
|
2005-02-02 20:08:57 +00:00
|
|
|
<h4>header</h4>
|
|
|
|
|
<p><strong>Since Ant 1.7</strong>, arbitrary mail headers can be added by
|
|
|
|
|
specifying these attributes on one or more nested header elements:</p>
|
|
|
|
|
|
|
|
|
|
<table width="60%" border="1" cellpadding="2" cellspacing="0">
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top"><b>Attribute</b></td>
|
|
|
|
|
<td valign="top"><b>Description</b></td>
|
|
|
|
|
<td align="center" valign="top"><b>Required</b></td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">name</td>
|
|
|
|
|
<td valign="top">The name associated with this mail header.</td>
|
|
|
|
|
<td align="center" valign="top">Yes</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">value</td>
|
|
|
|
|
<td valign="top">The value to assign to this mail header.</td>
|
|
|
|
|
<td align="center" valign="top">Yes</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
<p>It is permissible to duplicate the name attribute amongst multiple headers.
|
|
|
|
|
</p>
|
|
|
|
|
|
2001-02-13 12:32:01 +00:00
|
|
|
<h3>Examples</h3>
|
2002-02-05 09:32:48 +00:00
|
|
|
|
|
|
|
|
<blockquote><pre>
|
|
|
|
|
<mail from="me"
|
|
|
|
|
tolist="you"
|
|
|
|
|
subject="Results of nightly build"
|
2002-09-04 11:05:19 +00:00
|
|
|
files="build.log"/>
|
2002-02-05 09:32:48 +00:00
|
|
|
</pre></blockquote>
|
|
|
|
|
|
|
|
|
|
<p>Sends an email from <i>me</i> to <i>you</i> with a subject of
|
|
|
|
|
<i>Results of nightly build</i> and includes the contents of the file
|
|
|
|
|
<i>build.log</i> in the body of the message.</p>
|
|
|
|
|
|
|
|
|
|
<blockquote><pre>
|
|
|
|
|
<mail mailhost="smtp.myisp.com" mailport="1025" subject="Test build">
|
2003-05-15 11:30:27 +00:00
|
|
|
<from address="config@myisp.com"/>
|
|
|
|
|
<replyto address="me@myisp.com"/>
|
2003-03-28 15:03:55 +00:00
|
|
|
<to address="all@xyz.com"/>
|
2002-06-22 23:38:38 +00:00
|
|
|
<message>The ${buildname} nightly build has completed</message>
|
2005-11-29 04:44:04 +00:00
|
|
|
<attachments>
|
|
|
|
|
<fileset dir="dist">
|
|
|
|
|
<include name="**/*.zip"/>
|
|
|
|
|
</fileset>
|
|
|
|
|
</attachments>
|
2002-02-05 09:32:48 +00:00
|
|
|
</mail>
|
|
|
|
|
</pre></blockquote>
|
|
|
|
|
|
2003-05-15 11:30:27 +00:00
|
|
|
<p>Sends an eMail from <i>config@myisp.com</i> to <i>all@xyz.com</i> with a subject of
|
|
|
|
|
<i>Test Build</i>. Replies to this email will go to <i>me@myisp.com</i>.
|
|
|
|
|
Any zip files from the dist directory are attached. The
|
2002-02-05 09:32:48 +00:00
|
|
|
task will attempt to use JavaMail and fall back to UU encoding or no encoding in
|
2002-06-22 23:38:38 +00:00
|
|
|
that order depending on what support classes are available. <code>${buildname}</code>
|
|
|
|
|
will be replaced with the <code>buildname</code> property's value.</p>
|
2003-04-17 17:09:35 +00:00
|
|
|
|
|
|
|
|
<blockquote><pre>
|
|
|
|
|
<property name="line2" value="some_international_message"/>
|
|
|
|
|
<echo message="${line2}"/>
|
|
|
|
|
|
|
|
|
|
<mail mailhost="somehost@xyz.com" mailport="25" subject="Test build" charset="utf-8">
|
|
|
|
|
<from address="me@myist.com"/>
|
2004-11-19 09:07:12 +00:00
|
|
|
<to address="all@xyz.com"/>
|
2003-04-17 17:09:35 +00:00
|
|
|
<message>some international text:${line2}</message>
|
|
|
|
|
</mail>
|
|
|
|
|
</pre></blockquote>
|
|
|
|
|
|
|
|
|
|
<p>Sends an eMail from <i>me@myisp.com</i> to <i>all@xyz.com</i> with a subject of
|
|
|
|
|
<i>Test Build</i>, the message body being coded in UTF-8
|
|
|
|
|
|
2006-09-11 04:33:25 +00:00
|
|
|
|
2001-02-13 12:32:01 +00:00
|
|
|
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
