|
|
The Commons Email userguide.xml source code
<?xml version="1.0"?>
<!--
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.
-->
<document>
<properties>
<title>Examples
<author email="dev@commons.apache.org">Commons Documentation Team
<author email="quintonm@apache.org">Quinton McCombs
<revision>$Id: userguide.xml 560678 2007-07-29 04:38:09Z bspeakmon $
</properties>
<body>
<section name="A simple text email">
<p>
Our first example will create a basic email message to "John Doe" and
send it through your local mail server.
</p>
<source>
<![CDATA[
import org.apache.commons.mail.SimpleEmail;
...
SimpleEmail email = new SimpleEmail();
email.setHostName("mail.myserver.com");
email.addTo("jdoe@somewhere.org", "John Doe");
email.setFrom("me@apache.org", "Me");
email.setSubject("Test message");
email.setMsg("This is a simple test of commons-email");
email.send();
]]></source>
<p>
The call to setHostName("mail.myserver.com") sets the address of the
outgoing SMTP server that will be used to send the message. If this is
not set, the system property "mail.host" will be used.
</p>
</section>
<section name="Sending emails with attachments">
<p>
To add attachments to an email, you will need to use the MultiPartEmail
class. This class works just like SimpleEmail except that it adds
several overloaded attach() methods to add attachments to the email.
You can add an unlimited number of attachments either inline or
attached. The attachments will be MIME encoded.
</p>
<p>
The simpliest way to add the attachments is by using the EmailAttachment
class to reference your attachments.
</p>
<p>
In the following example, we will create an attachment for a picture.
We will then attach the picture to the email and send it.
</p>
<source>
<![CDATA[
import org.apache.commons.mail.*;
...
// Create the attachment
EmailAttachment attachment = new EmailAttachment();
attachment.setPath("mypictures/john.jpg");
attachment.setDisposition(EmailAttachment.ATTACHMENT);
attachment.setDescription("Picture of John");
attachment.setName("John");
// Create the email message
MultiPartEmail email = new MultiPartEmail();
email.setHostName("mail.myserver.com");
email.addTo("jdoe@somewhere.org", "John Doe");
email.setFrom("me@apache.org", "Me");
email.setSubject("The picture");
email.setMsg("Here is the picture you wanted");
// add the attachment
email.attach(attachment);
// send the email
email.send();
]]></source>
<p>
You can also use EmailAttachment to reference any valid URL for files
that you do not have locally. When the message is sent, the file will
be downloaded and attached to the message automatically.
</p>
<p>
The next example shows how we could have sent the apache logo
to John instead.
</p>
<source>
<![CDATA[
import org.apache.commons.mail.*;
...
// Create the attachment
EmailAttachment attachment = new EmailAttachment();
attachment.setURL(new URL("http://www.apache.org/images/asf_logo_wide.gif"));
attachment.setDisposition(EmailAttachment.ATTACHMENT);
attachment.setDescription("Apache logo");
attachment.setName("Apache logo");
// Create the email message
MultiPartEmail email = new MultiPartEmail();
email.setHostName("mail.myserver.com");
email.addTo("jdoe@somewhere.org", "John Doe");
email.setFrom("me@apache.org", "Me");
email.setSubject("The logo");
email.setMsg("Here is Apache's logo");
// add the attachment
email.attach(attachment);
// send the email
email.send();
]]></source>
</section>
<section name="Sending HTML formatted email">
<p>
Sending HTML formatted email is accomplished by using the HtmlEmail
class. This class works exactly like the MultiPartEmail class with
additional methods to set the html content, alternative text content
if the reciepient does not support HTML email, and add inline images.
</p>
<p>
In this example, we will send an email message with formatted HTML
content with an inline image.
</p>
<source>
<![CDATA[
import org.apache.commons.mail.HtmlEmail;
...
// Create the email message
HtmlEmail email = new HtmlEmail();
email.setHostName("mail.myserver.com");
email.addTo("jdoe@somewhere.org", "John Doe");
email.setFrom("me@apache.org", "Me");
email.setSubject("Test email with inline image");
// embed the image and get the content id
URL url = new URL("http://www.apache.org/images/asf_logo_wide.gif");
String cid = email.embed(url, "Apache logo");
// set the html message
email.setHtmlMsg("<html>The apache logo - ![](\"cid:"+cid+"\") |