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>
|
|
|
|
|
|
2018-01-22 23:52:21 +01:00
|
|
|
<h2 id="mail">Mail</h2>
|
2001-02-13 12:32:01 +00:00
|
|
|
<h3>Description</h3>
|
2018-02-28 07:58:59 +01: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 <code><attachments></code> elements, which
|
|
|
|
|
are <a href="../using.html#path">path-like structures</a>. This means any filesystem
|
|
|
|
|
based <a href="../Types/resources.html">resource</a> or resource collection can be used to point to
|
|
|
|
|
attachments. Prior to Apache 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.</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>
|
2018-02-28 07:58:59 +01:00
|
|
|
<table class="attr">
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
2018-05-15 10:29:27 +02:00
|
|
|
<th scope="col">Attribute</th>
|
|
|
|
|
<th scope="col">Description</th>
|
|
|
|
|
<th scope="col">Required</th>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>from</td>
|
|
|
|
|
<td>Email address of sender.</td>
|
|
|
|
|
<td>Either a <var>from</var> 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>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>replyto</td>
|
|
|
|
|
<td>Reply-to email address.</td>
|
|
|
|
|
<td>No</td>
|
2003-05-15 11:30:27 +00:00
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>tolist</td>
|
|
|
|
|
<td>Comma-separated list of recipients.</td>
|
|
|
|
|
<td rowspan="3">At least one of these, or the equivalent nested elements</td>
|
2002-02-05 09:32:48 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>cclist</td>
|
|
|
|
|
<td class="left">Comma-separated list of recipients to carbon copy</td>
|
2002-02-05 09:32:48 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>bcclist</td>
|
|
|
|
|
<td class="left">Comma-separated list of recipients to blind carbon copy
|
2005-11-16 19:43:32 +00:00
|
|
|
</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>message</td>
|
|
|
|
|
<td>Message to send in the body of the email.</td>
|
|
|
|
|
<td rowspan="2">One of these or a <code><message></code> element.</td>
|
2002-02-05 09:32:48 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>messagefile</td>
|
|
|
|
|
<td class="left">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>
|
2014-03-14 17:28:53 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>messagefileinputencoding</td>
|
|
|
|
|
<td>Specifies the encoding of the input file. Please
|
2018-03-08 07:43:53 +01:00
|
|
|
see <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html"
|
|
|
|
|
target="_top">Supported Encodings</a> for a list of possible values. <em>Since Ant 1.9.4</em>
|
2014-03-14 17:28:53 +00:00
|
|
|
</td>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>No; defaults to default JVM character encoding</td>
|
2014-03-14 17:28:53 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>messagemimetype</td>
|
|
|
|
|
<td>The content type of the message.</td>
|
|
|
|
|
<td>No; default is <q>text/plain</q></td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>files</td>
|
|
|
|
|
<td>Files to send as attachments to the email. Separate multiple file names using a comma or
|
|
|
|
|
space. You can also use <code><fileset></code> elements to specify files.</td>
|
|
|
|
|
<td>No</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
2002-01-02 05:16:41 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>failonerror</td>
|
|
|
|
|
<td>flag to indicate whether to halt the build on any error.</td>
|
|
|
|
|
<td>No; default is <q>true</q></td>
|
2002-02-05 09:32:48 +00:00
|
|
|
</tr>
|
2001-12-10 18:01:16 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>includefilenames</td>
|
|
|
|
|
<td>Include filename(s) before file contents.</td>
|
|
|
|
|
<td>No; default is <q>false</q>, ignored unless <q>plain</q> encoding is used</td>
|
2001-12-10 18:01:16 +00:00
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>mailhost</td>
|
|
|
|
|
<td>Host name of the SMTP server.</td>
|
|
|
|
|
<td>No; default is <q>localhost</q></td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
2001-11-15 22:11:28 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>mailport</td>
|
|
|
|
|
<td>TCP port of the SMTP server.</td>
|
|
|
|
|
<td>No; default is <q>25</q></td>
|
2002-02-05 09:32:48 +00:00
|
|
|
</tr>
|
2003-05-27 15:33:25 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>user</td>
|
|
|
|
|
<td>user name for SMTP auth</td>
|
|
|
|
|
<td>Yes, if SMTP auth is required on your SMTP server;<br/>the email message will be then sent
|
|
|
|
|
using MIME and requires JavaMail</td>
|
2003-05-27 15:33:25 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>password</td>
|
|
|
|
|
<td>password for SMTP auth</td>
|
|
|
|
|
<td>Yes, if SMTP auth is required on your SMTP server;<br/>the email message will be then sent
|
|
|
|
|
using MIME and requires JavaMail</td>
|
2003-05-27 15:33:25 +00:00
|
|
|
</tr>
|
2003-05-28 20:58:03 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>ssl</td>
|
|
|
|
|
<td><q>true</q>, <q>on</q>, or <q>yes</q> accepted here<br/>indicates whether you need
|
|
|
|
|
TLS/SSL</td>
|
|
|
|
|
<td>No</td>
|
2003-05-28 20:58:03 +00:00
|
|
|
</tr>
|
2002-02-05 09:32:48 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>encoding</td>
|
|
|
|
|
<td>Specifies the encoding to use for the content of the email. Values
|
|
|
|
|
are <q>mime</q>, <q>uu</q>, <q>plain</q>, or <q>auto</q>. <q>uu</q> or <q>plain</q> are not
|
|
|
|
|
compatible with SMTP auth</td>
|
|
|
|
|
<td>No; default is <q>auto</q></td>
|
2001-11-15 22:11:28 +00:00
|
|
|
</tr>
|
2003-04-17 17:09:35 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>charset</td>
|
|
|
|
|
<td>Character set of the email.<br/>You can also set the <var>charset</var> in
|
2018-03-02 08:23:45 +01:00
|
|
|
the <code>message</code> nested element.<br/> These options are mutually exclusive.</td>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>No</td>
|
2003-04-17 17:09:35 +00:00
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>subject</td>
|
|
|
|
|
<td>Email subject line.</td>
|
|
|
|
|
<td>No</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
2008-10-14 13:12:23 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>ignoreInvalidRecipients</td>
|
|
|
|
|
<td>(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>No; default is <q>false</q></td>
|
2008-10-14 13:12:23 +00:00
|
|
|
</tr>
|
2008-10-23 13:13:36 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>enableStartTLS</td>
|
|
|
|
|
<td>(boolean) Whether the <code>STARTTLS</code> command used to switch to an encrypted
|
|
|
|
|
connection for authentication should be supported. Requires JavaMail. <em>Since Ant
|
|
|
|
|
1.8.0</em></td>
|
|
|
|
|
<td>No</td>
|
2008-10-23 13:13:36 +00:00
|
|
|
</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>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p><em>Since Ant 1.6</em>, the
|
|
|
|
|
attributes <var>from</var>, <var>replyto</var>, <var>tolist</var>, <var>cclist</var>, <var>bcclist</var>
|
|
|
|
|
can contain email addresses of the form:</p>
|
2003-08-19 12:15:04 +00:00
|
|
|
<ul>
|
2018-02-28 07:58:59 +01:00
|
|
|
<li><samp>address@xyz.com</samp></li>
|
|
|
|
|
<li><samp>name <address@xyz.com></samp></li>
|
|
|
|
|
<li><samp><address@xyz.com> name</samp></li>
|
|
|
|
|
<li><samp>(name) address@xyz.com</samp></li>
|
|
|
|
|
<li><samp>address@xyz.com (name)</samp></li>
|
2003-08-19 12:15:04 +00:00
|
|
|
</ul>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>You need to enter the angle brackets as XML entities <q>&gt;</q> and <q>&lt;</q>.</p>
|
2003-08-19 12:15:04 +00:00
|
|
|
|
2002-02-05 09:32:48 +00:00
|
|
|
<h3>Parameters specified as nested elements</h3>
|
|
|
|
|
|
2018-01-22 23:52:21 +01: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>
|
|
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<table class="attr">
|
2002-02-05 09:32:48 +00:00
|
|
|
<tr>
|
2018-05-15 10:29:27 +02:00
|
|
|
<th scope="col">Attribute</th>
|
|
|
|
|
<th scope="col">Description</th>
|
|
|
|
|
<th scope="col">Required</th>
|
2002-02-05 09:32:48 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>name</td>
|
|
|
|
|
<td>The display name for the address.</td>
|
|
|
|
|
<td>No</td>
|
2002-02-05 09:32:48 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>address</td>
|
|
|
|
|
<td>The email address.</td>
|
|
|
|
|
<td>Yes</td>
|
2002-02-05 09:32:48 +00:00
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
<h4>message</h4>
|
|
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>Specifies the message to include in the email body. It takes the following attributes:</p>
|
2002-02-05 09:32:48 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<table class="attr">
|
2002-02-05 09:32:48 +00:00
|
|
|
<tr>
|
2018-05-15 10:29:27 +02:00
|
|
|
<th scope="col">Attribute</th>
|
|
|
|
|
<th scope="col">Description</th>
|
|
|
|
|
<th scope="col">Required</th>
|
2002-02-05 09:32:48 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>src</td>
|
|
|
|
|
<td>The file to use as the message.</td>
|
|
|
|
|
<td>No</td>
|
2002-02-05 09:32:48 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>mimetype</td>
|
|
|
|
|
<td>The content type to use for the message.</td>
|
|
|
|
|
<td>No</td>
|
2002-02-05 09:32:48 +00:00
|
|
|
</tr>
|
2003-04-17 17:09:35 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>charset</td>
|
|
|
|
|
<td>Character set of the message<br/>You can also set the <var>charset</var> as attribute of the
|
2018-03-02 08:23:45 +01:00
|
|
|
enclosing <code>mail</code> task.<br/> These options are mutually exclusive.</td>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>No</td>
|
2003-04-17 17:09:35 +00:00
|
|
|
</tr>
|
2014-03-14 17:28:53 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>inputencoding</td>
|
|
|
|
|
<td>
|
|
|
|
|
Specifies the encoding of the input file. Please
|
2018-03-08 07:43:53 +01:00
|
|
|
see <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html"
|
|
|
|
|
target="_top">Supported Encodings</a> for a list of possible values. <em>Since Ant 1.9.4</em>
|
2014-03-14 17:28:53 +00:00
|
|
|
</td>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>No; defaults to default JVM character encoding</td>
|
2014-03-14 17:28:53 +00:00
|
|
|
</tr>
|
2002-02-05 09:32:48 +00:00
|
|
|
</table>
|
|
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>If the <var>src</var> attribute is not specified, then text can be added 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>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p><em>Since Ant 1.7</em>, arbitrary mail headers can be added by specifying these attributes on one
|
|
|
|
|
or more nested header elements:</p>
|
2005-02-02 20:08:57 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<table class="attr">
|
2005-02-02 20:08:57 +00:00
|
|
|
<tr>
|
2018-05-15 10:29:27 +02:00
|
|
|
<th scope="col">Attribute</th>
|
|
|
|
|
<th scope="col">Description</th>
|
|
|
|
|
<th scope="col">Required</th>
|
2005-02-02 20:08:57 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>name</td>
|
|
|
|
|
<td>The name associated with this mail header.</td>
|
|
|
|
|
<td>Yes</td>
|
2005-02-02 20:08:57 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>value</td>
|
|
|
|
|
<td>The value to assign to this mail header.</td>
|
|
|
|
|
<td>Yes</td>
|
2005-02-02 20:08:57 +00:00
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
2018-01-24 21:40:28 +01:00
|
|
|
<p>It is permissible to duplicate the name attribute amongst multiple headers.</p>
|
2005-02-02 20:08:57 +00:00
|
|
|
|
2001-02-13 12:32:01 +00:00
|
|
|
<h3>Examples</h3>
|
2002-02-05 09:32:48 +00:00
|
|
|
|
2018-05-15 09:51:58 +02:00
|
|
|
<p>Send an email from <q>me</q> to <q>you</q> with a subject of <q>Results of nightly build</q> and
|
|
|
|
|
include the contents of the file <samp>build.log</samp> in the body of the message.</p>
|
|
|
|
|
|
2018-02-09 06:54:03 +01:00
|
|
|
<pre>
|
2002-02-05 09:32:48 +00:00
|
|
|
<mail from="me"
|
|
|
|
|
tolist="you"
|
|
|
|
|
subject="Results of nightly build"
|
2018-02-28 07:58:59 +01:00
|
|
|
files="build.log"/></pre>
|
2002-02-05 09:32:48 +00:00
|
|
|
|
2018-05-15 09:51:58 +02:00
|
|
|
<p>Send an email from <q>config@myisp.com</q> to <q>all@xyz.com</q> with a subject of <q>Test
|
|
|
|
|
Build</q>. Replies to this email will go to <q>me@myisp.com</q>. Any zip files from
|
|
|
|
|
the <samp>dist</samp> directory are attached. The task will attempt to use JavaMail and fall back to
|
|
|
|
|
UU encoding or no encoding in that order depending on what support classes are
|
|
|
|
|
available. <samp>${buildname}</samp> will be replaced with the <code>buildname</code> property's
|
|
|
|
|
value.</p>
|
2002-02-05 09:32:48 +00:00
|
|
|
|
2018-02-09 06:54:03 +01:00
|
|
|
<pre>
|
2002-02-05 09:32:48 +00:00
|
|
|
<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>
|
2018-02-28 07:58:59 +01:00
|
|
|
</mail></pre>
|
2002-02-05 09:32:48 +00:00
|
|
|
|
2018-05-15 09:51:58 +02:00
|
|
|
<p>Send an email from <q>me@myisp.com</q> to <q>all@xyz.com</q> with a subject of <q>Test Build</q>,
|
|
|
|
|
the message body being coded in UTF-8.
|
2003-04-17 17:09:35 +00:00
|
|
|
|
2018-02-09 06:54:03 +01:00
|
|
|
<pre>
|
2003-04-17 17:09:35 +00:00
|
|
|
<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>
|
2018-02-28 07:58:59 +01:00
|
|
|
</mail></pre>
|
2003-04-17 17:09:35 +00:00
|
|
|
|
2001-02-13 12:32:01 +00:00
|
|
|
</body>
|
|
|
|
|
</html>
|
