Module bus.extra
Package org.miaixz.bus.extra.mail

Class Mail

java.lang.Object
org.miaixz.bus.extra.mail.Mail
All Implemented Interfaces:
Serializable, org.miaixz.bus.core.Builder<jakarta.mail.internet.MimeMessage>
public class Mail extends Object implements org.miaixz.bus.core.Builder<jakarta.mail.internet.MimeMessage>
Represents a mail client for sending emails, designed with a fluent builder pattern. It simplifies the process of setting recipients, subject, content, and attachments. Supports both HTML and plain text content, and allows for file and image attachments.

Usage Example: 

 
 // Create a mail client
 Mail mail = Mail.of();

 // Set basic email information
 mail.setTos("recipient@example.com").setTitle("Email Subject").setContent("<h1>Hello!</h1>", true) // true indicates
                                                                                                    // HTML format
         .addFiles(new File("attachment.pdf"));

 // Send the email
 String messageId = mail.send();
Since:
Java 17+
Author:
Kimi Liu
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    Mail()
    Constructs a new Mail instance using the global mail account.
    Mail(MailAccount mailAccount)
    Constructs a new Mail instance with the specified mail account.

  • Method Summary

    Modifier and Type
    Method
    Description
    Mail
    addAttachments(jakarta.activation.DataSource... attachments)
    Adds attachments to the email, represented by DataSource objects.
    Mail
    addFiles(File... files)
    Adds file attachments to the email.
    Mail
    addImage(String cid, File imageFile)
    Adds an embedded image from a File to the email.
    Mail
    addImage(String cid, InputStream imageStream)
    Adds an embedded image to the email, referenced by a CID in the HTML body.
    Mail
    addImage(String cid, InputStream imageStream, String contentType)
    Adds an embedded image to the email with a specified content type.
    SMTPMessage
    build()
    Builds the MimeMessage object from the current configuration.
    static Mail
    of()
    Creates a new Mail instance using the global mail account configuration.
    static Mail
    of(MailAccount mailAccount)
    Creates a new Mail instance with the specified mail account.
    String
    send()
    Builds and sends the email.
    Mail
    setBccs(String... bccs)
    Sets multiple blind carbon copy (BCC) recipient email addresses, overwriting any previously set BCC recipients.
    Mail
    setCcs(String... ccs)
    Sets multiple carbon copy (CC) recipient email addresses, overwriting any previously set CC recipients.
    Mail
    setCharset(Charset charset)
    Sets the character set encoding for the email.
    Mail
    setContent(String content)
    Sets the body content of the email.
    Mail
    setContent(String content, boolean isHtml)
    Sets both the body content and the content type (HTML or plain text).
    Mail
    setDebugOutput(PrintStream debugOutput)
    Sets the debug output stream for logging mail sending details.
    Mail
    setHtml(boolean isHtml)
    Sets whether the email content is in HTML format.
    Mail
    setReply(String... reply)
    Sets multiple 'Reply-To' email addresses, overwriting any previously set reply-to addresses.
    Mail
    setTitle(String title)
    Sets the subject of the email.
    Mail
    setTos(String... tos)
    Sets multiple recipient email addresses, overwriting any previously set recipients.
    Mail
    setUseGlobalSession(boolean isUseGlobalSession)
    Sets whether to use a global session for sending mail.
    Mail
    to(String... tos)
    Sets the recipient email addresses.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Mail

      public Mail()
      Constructs a new Mail instance using the global mail account.

    • Mail

      public Mail(MailAccount mailAccount)
      Constructs a new Mail instance with the specified mail account. If the provided account is null, the global mail account configuration is used.
      Parameters:
      mailAccount - The mail account to use. If null, the global account is used.

  • Method Details

    • of

      public static Mail of(MailAccount mailAccount)
      Creates a new Mail instance with the specified mail account.
      Parameters:
      mailAccount - The mail account configuration.
      Returns:
      A new Mail instance.

    • of

      public static Mail of()
      Creates a new Mail instance using the global mail account configuration.
      Returns:
      A new Mail instance.

    • to

      public Mail to(String... tos)
      Sets the recipient email addresses.
      Parameters:
      tos - The recipient email addresses.
      Returns:
      This Mail instance for method chaining.
      See Also:

    • setTos

      public Mail setTos(String... tos)
      Sets multiple recipient email addresses, overwriting any previously set recipients.
      Parameters:
      tos - An array of recipient email addresses.
      Returns:
      This Mail instance for method chaining.

    • setCcs

      public Mail setCcs(String... ccs)
      Sets multiple carbon copy (CC) recipient email addresses, overwriting any previously set CC recipients.
      Parameters:
      ccs - An array of CC recipient email addresses.
      Returns:
      This Mail instance for method chaining.

    • setBccs

      public Mail setBccs(String... bccs)
      Sets multiple blind carbon copy (BCC) recipient email addresses, overwriting any previously set BCC recipients.
      Parameters:
      bccs - An array of BCC recipient email addresses.
      Returns:
      This Mail instance for method chaining.

    • setReply

      public Mail setReply(String... reply)
      Sets multiple 'Reply-To' email addresses, overwriting any previously set reply-to addresses.
      Parameters:
      reply - An array of 'Reply-To' email addresses.
      Returns:
      This Mail instance for method chaining.

    • setTitle

      public Mail setTitle(String title)
      Sets the subject of the email.
      Parameters:
      title - The subject of the email.
      Returns:
      This Mail instance for method chaining.

    • setContent

      public Mail setContent(String content)
      Sets the body content of the email. The content can be plain text or HTML. Use setHtml(boolean) to specify the content type.
      Parameters:
      content - The body content of the email.
      Returns:
      This Mail instance for method chaining.

    • setHtml

      public Mail setHtml(boolean isHtml)
      Sets whether the email content is in HTML format.
      Parameters:
      isHtml - true if the content is HTML, false for plain text.
      Returns:
      This Mail instance for method chaining.

    • setContent

      public Mail setContent(String content, boolean isHtml)
      Sets both the body content and the content type (HTML or plain text).
      Parameters:
      content - The body content of the email.
      isHtml - true if the content is HTML, false for plain text.
      Returns:
      This Mail instance for method chaining.

    • addFiles

      public Mail addFiles(File... files)
      Adds file attachments to the email. If a file is an image, a CID (Content-ID) is automatically generated for embedding in the email body, using the filename as the default CID.
      Parameters:
      files - An array of File objects to attach.
      Returns:
      This Mail instance for method chaining.

    • addImage

      public Mail addImage(String cid, InputStream imageStream)
      Adds an embedded image to the email, referenced by a CID in the HTML body. The image content type defaults to "image/jpeg".
      Parameters:
      cid - The Content-ID for embedding the image (e.g., "my-image").
      imageStream - The InputStream of the image. This stream is not closed by this method.
      Returns:
      This Mail instance for method chaining.

    • addImage

      public Mail addImage(String cid, InputStream imageStream, String contentType)
      Adds an embedded image to the email with a specified content type.
      Parameters:
      cid - The Content-ID for embedding the image.
      imageStream - The InputStream of the image. This stream is not closed by this method.
      contentType - The MIME type of the image (e.g., "image/png"). Defaults to "image/jpeg" if null.
      Returns:
      This Mail instance for method chaining.

    • addImage

      public Mail addImage(String cid, File imageFile)
      Adds an embedded image from a File to the email.
      Parameters:
      cid - The Content-ID for embedding the image.
      imageFile - The image File.
      Returns:
      This Mail instance for method chaining.

    • addAttachments

      public Mail addAttachments(jakarta.activation.DataSource... attachments)
      Adds attachments to the email, represented by DataSource objects.
      Parameters:
      attachments - An array of DataSource objects to attach.
      Returns:
      This Mail instance for method chaining.

    • setCharset

      public Mail setCharset(Charset charset)
      Sets the character set encoding for the email.
      Parameters:
      charset - The character set (e.g., UTF-8, GBK).
      Returns:
      This Mail instance for method chaining.
      See Also:

    • setUseGlobalSession

      public Mail setUseGlobalSession(boolean isUseGlobalSession)
      Sets whether to use a global session for sending mail. Defaults to false.
      Parameters:
      isUseGlobalSession - true to use a global session, false to create a new session for each email.
      Returns:
      This Mail instance for method chaining.

    • setDebugOutput

      public Mail setDebugOutput(PrintStream debugOutput)
      Sets the debug output stream for logging mail sending details.
      Parameters:
      debugOutput - The PrintStream for debug output. If null, system default is used.
      Returns:
      This Mail instance for method chaining.

    • build

      public SMTPMessage build()
      Builds the MimeMessage object from the current configuration. This method consolidates all settings into a complete mail message object ready for sending.
      Specified by:
      build in interface org.miaixz.bus.core.Builder<jakarta.mail.internet.MimeMessage>
      Returns:
      The constructed SMTPMessage object.

    • send

      public String send()
      Builds and sends the email.
      Returns:
      The unique message-id of the sent email, which can be used for tracking.
      Throws:
      org.miaixz.bus.core.lang.exception.InternalException - if sending the email fails.