| 1 | <html>
|
|---|
| 2 |
|
|---|
| 3 | <head>
|
|---|
| 4 | <meta http-equiv="Content-Language" content="en-us">
|
|---|
| 5 | <title>Mail Task</title>
|
|---|
| 6 | <link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css">
|
|---|
| 7 | </head>
|
|---|
| 8 |
|
|---|
| 9 | <body>
|
|---|
| 10 |
|
|---|
| 11 | <h2><a name="mail">Mail</a></h2>
|
|---|
| 12 | <h3>Description</h3>
|
|---|
| 13 | <p>A task to send SMTP email.<br></br><br></br>
|
|---|
| 14 | This task can send mail using either plain
|
|---|
| 15 | text, UU encoding, or MIME format mail, depending on what is available.<br></br><br></br>
|
|---|
| 16 | <br>
|
|---|
| 17 | SMTP auth and SSL/TLS require JavaMail and are only available in MIME format.<br></br><br></br>
|
|---|
| 18 | Attachments may be sent using nested
|
|---|
| 19 | <a href="../CoreTypes/fileset.html">fileset</a> elements.</p>
|
|---|
| 20 | <p><strong>Note:</strong> This task may depend on external libraries
|
|---|
| 21 | that are not included
|
|---|
| 22 | in the Ant distribution. See <a href="../install.html#librarydependencies">
|
|---|
| 23 | Library Dependencies</a> for more information.
|
|---|
| 24 | </p>
|
|---|
| 25 |
|
|---|
| 26 | <h3>Parameters</h3>
|
|---|
| 27 | <table border="1" cellpadding="2" cellspacing="0">
|
|---|
| 28 | <tr>
|
|---|
| 29 | <td valign="top"><b>Attribute</b></td>
|
|---|
| 30 | <td valign="top"><b>Description</b></td>
|
|---|
| 31 | <td align="center" valign="top"><b>Required</b></td>
|
|---|
| 32 | </tr>
|
|---|
| 33 | <tr>
|
|---|
| 34 | <td valign="top">from</td>
|
|---|
| 35 | <td valign="top">Email address of sender.</td>
|
|---|
| 36 | <td align="center" valign="top">Either a <code>from</code> attribute, or a <code><from></code>
|
|---|
| 37 | element.</td>
|
|---|
| 38 | </tr>
|
|---|
| 39 | <tr>
|
|---|
| 40 | <td valign="top">replyto</td>
|
|---|
| 41 | <td valign="top">Replyto email address.</td>
|
|---|
| 42 | <td align="center" valign="top">No</td>
|
|---|
| 43 | </tr>
|
|---|
| 44 | <tr>
|
|---|
| 45 | <td valign="top">tolist</td>
|
|---|
| 46 | <td valign="top">Comma-separated list of recipients.</td>
|
|---|
| 47 | <td align="center" valign="middle" rowspan="3">At least one of these, or the
|
|---|
| 48 | equivalent elements.</td>
|
|---|
| 49 | </tr>
|
|---|
| 50 | <tr>
|
|---|
| 51 | <td valign="top">cclist</td>
|
|---|
| 52 | <td valign="top">Comma-separated list of recipients to carbon copy</td>
|
|---|
| 53 | </tr>
|
|---|
| 54 | <tr>
|
|---|
| 55 | <td valign="top">bcclist</td>
|
|---|
| 56 | <td valign="top">Comma-separated list of recipients to carbon copy</td>
|
|---|
| 57 | </tr>
|
|---|
| 58 | <tr>
|
|---|
| 59 | <td valign="top">message</td>
|
|---|
| 60 | <td valign="top">Message to send in the body of the email.</td>
|
|---|
| 61 | <td align="center" valign="middle" rowspan="2">One of these or a
|
|---|
| 62 | <code><message></code> element.</td>
|
|---|
| 63 | </tr>
|
|---|
| 64 | <tr>
|
|---|
| 65 | <td valign="top">messagefile</td>
|
|---|
| 66 | <td valign="top">File to send as the body of the email. Property
|
|---|
| 67 | values in the file will be expanded.</td>
|
|---|
| 68 | </tr>
|
|---|
| 69 | <td valign="top">messagemimetype</td>
|
|---|
| 70 | <td valign="top">The content type of the message. The default is
|
|---|
| 71 | <code>text/plain</code>.</td>
|
|---|
| 72 | <td align="center" valign="top">No</td>
|
|---|
| 73 | </tr>
|
|---|
| 74 | <tr>
|
|---|
| 75 | <td valign="top">files</td>
|
|---|
| 76 | <td valign="top">Files to send as attachments to the email. Separate multiple
|
|---|
| 77 | file names using a comma or space. You can also use <code><fileset></code>
|
|---|
| 78 | elements to specify files.</td>
|
|---|
| 79 | <td align="center" valign="top">No</td>
|
|---|
| 80 | </tr>
|
|---|
| 81 | <tr>
|
|---|
| 82 | <td valign="top">failonerror</td>
|
|---|
| 83 | <td valign="top">flag to indicate whether to halt the build on
|
|---|
| 84 | any error. The default value is <code>true</code>.</td>
|
|---|
| 85 | <td align="center" valign="top">No.</td>
|
|---|
| 86 | </tr>
|
|---|
| 87 | <tr>
|
|---|
| 88 | <td valign="top">includefilenames</td>
|
|---|
| 89 | <td valign="top">Include filename(s) before file contents.
|
|---|
| 90 | Valid only when the <code>plain</code> encoding is used. The default
|
|---|
| 91 | value is <code>false</code>.</td>
|
|---|
| 92 | <td align="center" valign="top">No</td>
|
|---|
| 93 | </tr>
|
|---|
| 94 | <tr>
|
|---|
| 95 | <td valign="top">mailhost</td>
|
|---|
| 96 | <td valign="top">Host name of the SMTP server. The default value is
|
|---|
| 97 | <code>localhost</code>.</td>
|
|---|
| 98 | <td align="center" valign="top">No</td>
|
|---|
| 99 | </tr>
|
|---|
| 100 | <tr>
|
|---|
| 101 | <td valign="top">mailport</td>
|
|---|
| 102 | <td valign="top">TCP port of the SMTP server. The default value is 25.</td>
|
|---|
| 103 | <td align="center" valign="top">No</td>
|
|---|
| 104 | </tr>
|
|---|
| 105 | <tr>
|
|---|
| 106 | <td valign="top">user</td>
|
|---|
| 107 | <td valign="top">user name for SMTP auth</td>
|
|---|
| 108 | <td valign="center">Yes, if SMTP auth is required on your SMTP server<br></br>
|
|---|
| 109 | the email message will be then sent using Mime and requires JavaMail</td>
|
|---|
| 110 | </tr>
|
|---|
| 111 | <tr>
|
|---|
| 112 | <td valign="top">password</td>
|
|---|
| 113 | <td valign="top">password for SMTP auth</td>
|
|---|
| 114 | <td valign="center">Yes, if SMTP auth is required on your SMTP server<br></br>
|
|---|
| 115 | the email message will be then sent using Mime and requires JavaMail</td>
|
|---|
| 116 | </tr>
|
|---|
| 117 | <tr>
|
|---|
| 118 | <td valign="top">ssl</td>
|
|---|
| 119 | <td valign="top">"true", "on" or "yes" accepted here<br></br>
|
|---|
| 120 | indicates whether you need TLS/SSL</td>
|
|---|
| 121 | <td valign="center">No</td>
|
|---|
| 122 | </tr>
|
|---|
| 123 | <tr>
|
|---|
| 124 | <td valign="top">encoding</td>
|
|---|
| 125 | <td valign="top">Specifies the encoding to use for the content of the email.
|
|---|
| 126 | Values are <code>mime</code>, <code>uu</code>, <code>plain</code>, or
|
|---|
| 127 | <code>auto</code>. The default value is <code>auto</code>.
|
|---|
| 128 | <code>uu</code> or <code>plain</code> are not compatible with SMTP auth</td>
|
|---|
| 129 | <td align="center" valign="top">No</td>
|
|---|
| 130 | </tr>
|
|---|
| 131 | <tr>
|
|---|
| 132 | <td valign="top">charset</td>
|
|---|
| 133 | <td valign="top">Character set of the email.<br>
|
|---|
| 134 | You can also set the charset in the message nested element.<br>
|
|---|
| 135 | These options are mutually exclusive.</td>
|
|---|
| 136 | <td align="center" valign="top">No</td>
|
|---|
| 137 | </tr>
|
|---|
| 138 | <tr>
|
|---|
| 139 | <td valign="top">subject</td>
|
|---|
| 140 | <td valign="top">Email subject line.</td>
|
|---|
| 141 | <td align="center" valign="top">No</td>
|
|---|
| 142 | </tr>
|
|---|
| 143 | </table>
|
|---|
| 144 |
|
|---|
| 145 | <h3>Note regarding the attributes containing email addresses</h3>
|
|---|
| 146 | Since ant 1.6, the attributes from, replyto, tolist, cclist, bcclist
|
|---|
| 147 | can contain email addresses of the form :
|
|---|
| 148 | <ul>
|
|---|
| 149 | <li>[email protected]</li>
|
|---|
| 150 | <li>name <[email protected]></li>
|
|---|
| 151 | <li><[email protected]> name</li>
|
|---|
| 152 | <li>(name) [email protected]</li>
|
|---|
| 153 | <li>[email protected] (name)</li>
|
|---|
| 154 | </ul>
|
|---|
| 155 | <p>You need to enter the angle brackets as XML entities
|
|---|
| 156 | <code>&gt;</code> and <code>&lt;</code>.</p>
|
|---|
| 157 |
|
|---|
| 158 | <h3>Parameters specified as nested elements</h3>
|
|---|
| 159 |
|
|---|
| 160 | <h4>to / cc / bcc / from/ replyto </h4>
|
|---|
| 161 | <p>Adds an email address element. It takes the following attributes:</p>
|
|---|
| 162 |
|
|---|
| 163 | <table width="60%" border="1" cellpadding="2" cellspacing="0">
|
|---|
| 164 | <tr>
|
|---|
| 165 | <td valign="top"><b>Attribute</b></td>
|
|---|
| 166 | <td valign="top"><b>Description</b></td>
|
|---|
| 167 | <td align="center" valign="top"><b>Required</b></td>
|
|---|
| 168 | </tr>
|
|---|
| 169 | <tr>
|
|---|
| 170 | <td valign="top">name</td>
|
|---|
| 171 | <td valign="top">The display name for the address.</td>
|
|---|
| 172 | <td align="center" valign="top">No</td>
|
|---|
| 173 | </tr>
|
|---|
| 174 | <tr>
|
|---|
| 175 | <td valign="top">address</td>
|
|---|
| 176 | <td valign="top">The email address.</td>
|
|---|
| 177 | <td align="center" valign="top">Yes</td>
|
|---|
| 178 | </tr>
|
|---|
| 179 | </table>
|
|---|
| 180 |
|
|---|
| 181 | <h4>message</h4>
|
|---|
| 182 |
|
|---|
| 183 | <p>Specifies the message to include in the email body. It takes the following
|
|---|
| 184 | attributes:</p>
|
|---|
| 185 |
|
|---|
| 186 | <table width="60%" border="1" cellpadding="2" cellspacing="0">
|
|---|
| 187 | <tr>
|
|---|
| 188 | <td valign="top"><b>Attribute</b></td>
|
|---|
| 189 | <td valign="top"><b>Description</b></td>
|
|---|
| 190 | <td align="center" valign="top"><b>Required</b></td>
|
|---|
| 191 | </tr>
|
|---|
| 192 | <tr>
|
|---|
| 193 | <td valign="top">src</td>
|
|---|
| 194 | <td valign="top">The file to use as the message.</td>
|
|---|
| 195 | <td align="center" valign="top">No</td>
|
|---|
| 196 | </tr>
|
|---|
| 197 | <tr>
|
|---|
| 198 | <td valign="top">mimetype</td>
|
|---|
| 199 | <td valign="top">The content type to use for the message.</td>
|
|---|
| 200 | <td align="center" valign="top">No</td>
|
|---|
| 201 | </tr>
|
|---|
| 202 | <tr>
|
|---|
| 203 | <td valign="top">charset</td>
|
|---|
| 204 | <td valign="top">Character set of the message<br>
|
|---|
| 205 | You can also set the charset as attribute of the enclosing mail task.<br>
|
|---|
| 206 | These options are mutually exclusive.</td>
|
|---|
| 207 | <td align="center" valign="top">No</td>
|
|---|
| 208 | </tr>
|
|---|
| 209 | </table>
|
|---|
| 210 |
|
|---|
| 211 | <p>If the <code>src</code> attribute is not specified, then text can be added
|
|---|
| 212 | inside the <code><message></code> element. Property expansion will occur
|
|---|
| 213 | in the message, whether it is specified as an external file or as text within
|
|---|
| 214 | the <code><message></code> element.</p>
|
|---|
| 215 |
|
|---|
| 216 | <h3>Examples</h3>
|
|---|
| 217 |
|
|---|
| 218 | <blockquote><pre>
|
|---|
| 219 | <mail from="me"
|
|---|
| 220 | tolist="you"
|
|---|
| 221 | subject="Results of nightly build"
|
|---|
| 222 | files="build.log"/>
|
|---|
| 223 | </pre></blockquote>
|
|---|
| 224 |
|
|---|
| 225 | <p>Sends an email from <i>me</i> to <i>you</i> with a subject of
|
|---|
| 226 | <i>Results of nightly build</i> and includes the contents of the file
|
|---|
| 227 | <i>build.log</i> in the body of the message.</p>
|
|---|
| 228 |
|
|---|
| 229 | <blockquote><pre>
|
|---|
| 230 | <mail mailhost="smtp.myisp.com" mailport="1025" subject="Test build">
|
|---|
| 231 | <from address="[email protected]"/>
|
|---|
| 232 | <replyto address="[email protected]"/>
|
|---|
| 233 | <to address="[email protected]"/>
|
|---|
| 234 | <message>The ${buildname} nightly build has completed</message>
|
|---|
| 235 | <fileset dir="dist">
|
|---|
| 236 | <includes name="**/*.zip"/>
|
|---|
| 237 | </fileset>
|
|---|
| 238 | </mail>
|
|---|
| 239 | </pre></blockquote>
|
|---|
| 240 |
|
|---|
| 241 | <p>Sends an eMail from <i>[email protected]</i> to <i>[email protected]</i> with a subject of
|
|---|
| 242 | <i>Test Build</i>. Replies to this email will go to <i>[email protected]</i>.
|
|---|
| 243 | Any zip files from the dist directory are attached. The
|
|---|
| 244 | task will attempt to use JavaMail and fall back to UU encoding or no encoding in
|
|---|
| 245 | that order depending on what support classes are available. <code>${buildname}</code>
|
|---|
| 246 | will be replaced with the <code>buildname</code> property's value.</p>
|
|---|
| 247 |
|
|---|
| 248 | <blockquote><pre>
|
|---|
| 249 | <property name="line2" value="some_international_message"/>
|
|---|
| 250 | <echo message="${line2}"/>
|
|---|
| 251 |
|
|---|
| 252 | <mail mailhost="[email protected]" mailport="25" subject="Test build" charset="utf-8">
|
|---|
| 253 | <from address="[email protected]"/>
|
|---|
| 254 | <to address="[email protected]" />
|
|---|
| 255 | <message>some international text:${line2}</message>
|
|---|
| 256 | </mail>
|
|---|
| 257 | </pre></blockquote>
|
|---|
| 258 |
|
|---|
| 259 | <p>Sends an eMail from <i>[email protected]</i> to <i>[email protected]</i> with a subject of
|
|---|
| 260 | <i>Test Build</i>, the message body being coded in UTF-8
|
|---|
| 261 |
|
|---|
| 262 | <hr>
|
|---|
| 263 | <p align="center">Copyright © 2000-2004 The Apache Software Foundation. All rights
|
|---|
| 264 | Reserved.</p>
|
|---|
| 265 |
|
|---|
| 266 | </body>
|
|---|
| 267 | </html>
|
|---|
