germuska 2004/11/14 13:15:33
Modified: email/xdocs examples.xml
email/src/java/org/apache/commons/mail Email.java
Log:
add support for bounce handling and document in examples.xml
Revision Changes Path
1.4 +32 -1 jakarta-commons-sandbox/email/xdocs/examples.xml
Index: examples.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/email/xdocs/examples.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- examples.xml 19 Feb 2004 23:21:41 -0000 1.3
+++ examples.xml 14 Nov 2004 21:15:33 -0000 1.4
@@ -193,6 +193,37 @@
</p>
</section>
+ <section name="Handling Bounced Messages">
+ <p>
+ Normally, messages which cannot be delivered to a recipient are
returned to the
+ sender (specified with the <code>from</code> property). However, in
some cases,
+ you'll want these to be sent to a different address. To do this,
simply call the
+ <code>setBounceAddress(emailAddressString)</code> method before
sending
+ your email.
+ </p>
+ <p>
+ Technical notes: When SMTP servers cannot deliver mail, they do not
pay any attention
+ to the contents of the message to determine where the error
notification should be
+ sent. Rather, they refer to the SMTP "envelope sender" value.
JavaMail sets this
+ value according to the value of the <code>mail.smtp.from</code>
property on the
+ JavaMail <code>Session</code>. (Commons Email initializes the
JavaMail
+ <code>Session</code> using <code>System.getProperties()</code>)
+ If this property has not been set, then JavaMail
+ uses the "from" address. If your email bean has the
<code>bounceAddress</code>
+ property set, then Commons Email uses it to set the value of
<code>mail.smtp.from</code>
+ when the <code>Session</code> is initialized, overriding any other
value
+ which might have been set.
+ </p>
+ <p>
+ <em>Note: </em> This is the only way to control the handling of
bounced email.
+ Specifically, the "Errors-to:" SMTP header is deprecated and cannot
be trusted
+ to control how a bounced message will be handled. Also note that it
is considered bad
+ practice to send email with an untrusted "from" address unless you
also set the
+ bounce address. If your application allows users to enter an
address which is used
+ as the "from" address on an email, you should be sure to set the
bounce address
+ to a known good address.
+ </p>
+ </section>
</body>
</document>
1.26 +31 -2
jakarta-commons-sandbox/email/src/java/org/apache/commons/mail/Email.java
Index: Email.java
===================================================================
RCS file:
/home/cvs/jakarta-commons-sandbox/email/src/java/org/apache/commons/mail/Email.java,v
retrieving revision 1.25
retrieving revision 1.26
diff -u -r1.25 -r1.26
--- Email.java 29 Oct 2004 12:06:40 -0000 1.25
+++ Email.java 14 Nov 2004 21:15:33 -0000 1.26
@@ -162,6 +162,14 @@
/** List of "replyTo" email adresses */
protected ArrayList replyList = new ArrayList();
+ /**
+ * Address to which undeliverable mail should be sent.
+ * Because this is handled by JavaMail as a String property
+ * in the mail session, this property is of type <code>String</code>
+ * rather than <code>InternetAddress</code>.
+ */
+ protected String bounceAddress = null;
+
/**
* Used to specify the mail headers. Example:
*
@@ -172,7 +180,7 @@
protected Hashtable headers = new Hashtable();
/**
- * Used to determine wether to use pop3 before smtp, and if so the
settings.
+ * Used to determine whether to use pop3 before smtp, and if so the
settings.
*/
/** */
@@ -357,6 +365,11 @@
properties.setProperty(MAIL_SMTP_AUTH, "true");
}
+ if (this.bounceAddress != null)
+ {
+ properties.setProperty(MAIL_SMTP_FROM, this.bounceAddress);
+ }
+
// changed this (back) to getInstance due to security exceptions
// caused when testing using maven
this.session =
@@ -725,6 +738,22 @@
this.subject = aSubject;
return this;
}
+
+ /**
+ * Set the "bounce address" - the address to which undeliverable messages
+ * will be returned. If this value is never set, then the message will
be
+ * sent to the address specified with the System property
"mail.smtp.from",
+ * or if that value is not set, then to the "from" address.
+ *
+ * @param email A String.
+ * @return An Email.
+ */
+ public Email setBounceAddress(String email)
+ {
+ this.bounceAddress = email;
+ return this;
+ }
+
/**
* Define the content of the mail. It should be overidden by the
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
