Mail Task

## Mail

### Description

A task to send SMTP email.

This task can send mail using either plain text, UU encoding, or MIME format mail, depending on what is available.

SMTP auth and SSL/TLS require JavaMail or JakartaMail and are only available in MIME format.

Attachments may be sent using nested `<attachments>` elements, which are path-like structures. This means any filesystem based resource or resource collection can be used to point to attachments. Prior to Apache Ant 1.7 only `<fileset>` has been supported as a nested element, you can still use this directly without an `<attachments>` container.

Note: This task may depend on external libraries that are not included in the Ant distribution. See Library Dependencies for more information.

Starting with Ant 1.10.13 Ant supports either the modern `jakarta.mail` as well as the older `javax.mail` implementations and will prefer `jakarta.mail` if both are available.

### Parameters

Attribute | Description | Required
--- | --- | ---
from | Email address of sender. | Either a from attribute, or a `<from>` element.
replyto | Reply-to email address. | No
tolist | Comma-separated list of recipients. | At least one of these, or the equivalent nested elements
cclist | Comma-separated list of recipients to carbon copy
bcclist | Comma-separated list of recipients to blind carbon copy
message | Message to send in the body of the email. | One of these or a `<message>` element.
messagefile | File to send as the body of the email. Property values in the file will be expanded.
messagefileinputencoding | Specifies the encoding of the input file. Please see Supported Encodings for a list of possible values. Since Ant 1.9.4 | No; defaults to default JVM character encoding
messagemimetype | The content type of the message. | No; default is text/plain
files | Files to send as attachments to the email. Separate multiple file names using a comma or space. You can also use `<fileset>` elements to specify files. | No
failonerror | flag to indicate whether to halt the build on any error. | No; default is true
includefilenames | Include filename(s) before file contents. | No; default is false, ignored unless plain encoding is used
mailhost | Host name of the SMTP server. | No; default is localhost
mailport | TCP port of the SMTP server. | No; default is 25
user | user name for SMTP auth | Yes, if SMTP auth is required on your SMTP server; the email message will be then sent using MIME and requires JavaMail
password | password for SMTP auth | Yes, if SMTP auth is required on your SMTP server; the email message will be then sent using MIME and requires JavaMail
ssl | true, on, or yes accepted here indicates whether you need TLS/SSL | No
encoding | Specifies the encoding to use for the content of the email. Values are mime, uu, plain, or auto. uu or plain are not compatible with SMTP auth | No; default is auto
charset | Character set of the email. You can also set the charset in the `message` nested element. These options are mutually exclusive. | No
subject | Email subject line. | No
ignoreInvalidRecipients | (boolean) Whether the task should try to send the message to as many recipients as possible and should only fail if neither is reachable. Since Ant 1.8.0. | No; default is false
enableStartTLS | (boolean) Whether the `STARTTLS` command used to switch to an encrypted connection for authentication should be supported. Requires JavaMail. Since Ant 1.8.0 | No

### Note regarding the attributes containing email addresses

Since Ant 1.6, the attributes from, replyto, tolist, cclist, bcclist can contain email addresses of the form:

- `address@xyz.com`
- `name <address@xyz.com>`
- `<address@xyz.com> name`
- `(name) address@xyz.com`
- `address@xyz.com (name)`

You need to enter the angle brackets as XML entities &gt; and &lt;.

### Parameters specified as nested elements

#### to / cc / bcc / from/ replyto

Adds an email address element. It takes the following attributes:

Attribute | Description | Required
--- | --- | ---
name | The display name for the address. | No
address | The email address. | Yes

#### message

Specifies the message to include in the email body. It takes the following attributes:

Attribute | Description | Required
--- | --- | ---
src | The file to use as the message. | No
mimetype | The content type to use for the message. | No
charset | Character set of the message You can also set the charset as attribute of the enclosing `mail` task. These options are mutually exclusive. | No
inputencoding | Specifies the encoding of the input file. Please see Supported Encodings for a list of possible values. Since Ant 1.9.4 | No; defaults to default JVM character encoding

If the src attribute is not specified, then text can be added inside the `<message>` element. Property expansion will occur in the message, whether it is specified as an external file or as text within the `<message>` element.

#### header

Since Ant 1.7, arbitrary mail headers can be added by specifying these attributes on one or more nested header elements:

Attribute | Description | Required
--- | --- | ---
name | The name associated with this mail header. | Yes
value | The value to assign to this mail header. | Yes

It is permissible to duplicate the name attribute amongst multiple headers.

### Examples

Send an email from me to you with a subject of Results of nightly build and include the contents of the file `build.log` in the body of the message.

    <mail from="me"
          tolist="you"
          subject="Results of nightly build"
          files="build.log"/>

Send an email from config@myisp.com to all@xyz.com with a subject of Test Build. Replies to this email will go to me@myisp.com. Any zip files from the `dist` 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. `${buildname}` will be replaced with the `buildname` property's value.

    <mail mailhost="smtp.myisp.com" mailport="1025" subject="Test build">
      <from address="config@myisp.com"/>
      <replyto address="me@myisp.com"/>
      <to address="all@xyz.com"/>
      <message>The ${buildname} nightly build has completed</message>
      <attachments>
        <fileset dir="dist">
          <include name="**/*.zip"/>
        </fileset>
      </attachments>
    </mail>

Send an email from me@myisp.com to all@xyz.com with a subject of Test Build, the message body being coded in UTF-8.

    <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"/>
      <to address="all@xyz.com"/>
      <message>some international text:${line2}</message>
    </mail>