MailMessage (Apache Ant API)
Date: 2018-09-12

Package org.apache.tools.mail

## Class MailMessage

- java.lang.Object
- - org.apache.tools.mail.MailMessage

-     public class MailMessage
      extends java.lang.Object

  A class to help send SMTP email. This class is an improvement on the sun.net.smtp.SmtpClient class found in the JDK. This version has extra functionality, and can be used with JVMs that did not extend from the JDK. It's not as robust as the JavaMail Standard Extension classes, but it's easier to use and easier to install, and has an Open Source license.

  It can be used like this:

       String mailhost = "localhost";  // or another mail host
       String from = "Mail Message Servlet <MailMessage@server.com>";
       String to = "to@you.com";
       String cc1 = "cc1@you.com";
       String cc2 = "cc2@you.com";
       String bcc = "bcc@you.com";

       MailMessage msg = new MailMessage(mailhost);
       msg.setPort(25);
       msg.from(from);
       msg.to(to);
       msg.cc(cc1);
       msg.cc(cc2);
       msg.bcc(bcc);
       msg.setSubject("Test subject");
       PrintStream out = msg.getPrintStream();

       Enumeration enum = req.getParameterNames();
       while (enum.hasMoreElements()) {
         String name = (String) enum.nextElement();
         String value = req.getParameter(name);
         out.println(name + " = " + value);
       }

       msg.sendAndClose();

  Be sure to set the from address, then set the recipient addresses, then set the subject and other headers, then get the PrintStream, then write the message, and finally send and close. The class does minimal error checking internally; it counts on the mail host to complain if there's any malformatted input or out of order execution.

  An attachment mechanism based on RFC 1521 could be implemented on top of this class. In the meanwhile, JavaMail is the best solution for sending email with attachments.

  Still to do:

  - Figure out how to close the connection in case of error
  Version:
    1.1, 2000/03/19, added angle brackets to address, helps some servers version 1.0, 1999/12/29

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `DEFAULT_HOST` | default mailhost
    `static int` | `DEFAULT_PORT` | default port for SMTP: 25

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `MailMessage()` | Constructs a new MailMessage to send an email.
    `MailMessage​(java.lang.String host)` | Constructs a new MailMessage to send an email.
    `MailMessage​(java.lang.String host, int port)` | Constructs a new MailMessage to send an email.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `bcc​(java.lang.String bcc)` | Sets the bcc address.
    `void` | `cc​(java.lang.String cc)` | Sets the cc address.
    `void` | `from​(java.lang.String from)` | Sets the from address.
    `java.io.PrintStream` | `getPrintStream()` | Returns a PrintStream that can be used to write the body of the message.
    `void` | `replyto​(java.lang.String rto)` | Sets the replyto address This method may be called multiple times.
    `void` | `sendAndClose()` | Sends the message and closes the connection to the server.
    `void` | `setHeader​(java.lang.String name, java.lang.String value)` | Sets the named header to the given value.
    `void` | `setPort​(int port)` | Set the port to connect to the SMTP host.
    `void` | `setSubject​(java.lang.String subj)` | Sets the subject of the mail message.
    `void` | `to​(java.lang.String to)` | Sets the to address.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### DEFAULT_HOST

          public static final java.lang.String DEFAULT_HOST

      default mailhost
      See Also:
        Constant Field Values

    - #### DEFAULT_PORT

          public static final int DEFAULT_PORT

      default port for SMTP: 25
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### MailMessage

          public MailMessage()
                      throws java.io.IOException

      Constructs a new MailMessage to send an email. Use localhost as the mail server with port 25.
      Throws:
        `java.io.IOException` - if there's any problem contacting the mail server

    - #### MailMessage

          public MailMessage​(java.lang.String host)
                      throws java.io.IOException

      Constructs a new MailMessage to send an email. Use the given host as the mail server with port 25.
      Parameters:
        `host` - the mail server to use
      Throws:
        `java.io.IOException` - if there's any problem contacting the mail server

    - #### MailMessage

          public MailMessage​(java.lang.String host,
                             int port)
                      throws java.io.IOException

      Constructs a new MailMessage to send an email. Use the given host and port as the mail server.
      Parameters:
        `host` - the mail server to use
        `port` - the port to connect to
      Throws:
        `java.io.IOException` - if there's any problem contacting the mail server

  - ### Method Detail

    - #### setPort

          public void setPort​(int port)

      Set the port to connect to the SMTP host.
      Parameters:
        `port` - the port to use for connection.
      See Also:
        `DEFAULT_PORT`

    - #### from

          public void from​(java.lang.String from)
                    throws java.io.IOException

      Sets the from address. Also sets the "From" header. This method should be called only once.
      Parameters:
        `from` - the from address
      Throws:
        `java.io.IOException` - if there's any problem reported by the mail server

    - #### replyto

          public void replyto​(java.lang.String rto)

      Sets the replyto address This method may be called multiple times.
      Parameters:
        `rto` - the replyto address

    - #### to

          public void to​(java.lang.String to)
                  throws java.io.IOException

      Sets the to address. Also sets the "To" header. This method may be called multiple times.
      Parameters:
        `to` - the to address
      Throws:
        `java.io.IOException` - if there's any problem reported by the mail server

    - #### cc

          public void cc​(java.lang.String cc)
                  throws java.io.IOException

      Sets the cc address. Also sets the "Cc" header. This method may be called multiple times.
      Parameters:
        `cc` - the cc address
      Throws:
        `java.io.IOException` - if there's any problem reported by the mail server

    - #### bcc

          public void bcc​(java.lang.String bcc)
                   throws java.io.IOException

      Sets the bcc address. Does NOT set any header since it's a *blind* copy. This method may be called multiple times.
      Parameters:
        `bcc` - the bcc address
      Throws:
        `java.io.IOException` - if there's any problem reported by the mail server

    - #### setSubject

          public void setSubject​(java.lang.String subj)

      Sets the subject of the mail message. Actually sets the "Subject" header.
      Parameters:
        `subj` - the subject of the mail message

    - #### setHeader

          public void setHeader​(java.lang.String name,
                                java.lang.String value)

      Sets the named header to the given value. RFC 822 provides the rules for what text may constitue a header name and value.
      Parameters:
        `name` - name of the header
        `value` - contents of the header

    - #### getPrintStream

          public java.io.PrintStream getPrintStream()
                                             throws java.io.IOException

      Returns a PrintStream that can be used to write the body of the message. A stream is used since email bodies are byte-oriented. A writer can be wrapped on top if necessary for internationalization. This is actually done in Message.java
      Returns:
        a printstream containing the data and the headers of the email
      Throws:
        `java.io.IOException` - if there's any problem reported by the mail server
      See Also:
        `Message`

    - #### sendAndClose

          public void sendAndClose()
                            throws java.io.IOException

      Sends the message and closes the connection to the server. The MailMessage object cannot be reused.
      Throws:
        `java.io.IOException` - if there's any problem reported by the mail server