senselogic.sitevision.api.mail

Interface MailBuilder

All Superinterfaces:

Builder<Mail>

@Requireable(value="MailBuilder")
public interface MailBuilder
extends Builder<Mail>

Builder to create a Mail instances that can be sent.

MailBuilder has some mandatory attributes:

• subject - The mail subject. Must be non-null.
• message - The mail message. Can be a text message (text/plain), a html message (text/html), or both. Must be non-null.
• recipients - The mail recipient (TO). At least one recipient must be added.

MailBuilder also has some optional attributes:

• fromAddress - The from address. Default is null (will use the from address for the site, with fallback to the from address of the server).
• copyRecipients - The carbon copy recipients (CC). Default is null.
• blindCopyRecipients - The blind carbon copy recipients (BCC). Default is null.
• replyTos - The reply-to addresses. Default is null.

Note that there are three types of recipients (TO, CC, BCC). This builder will not detect or automatically handle duplicates cross types. It is up to the mail builder user to ensure addresses aren't added as different types of recipients.

Using the MailBuilder is pretty straightforward, if you remember that it is stateful. Conceptually you would typically use it like this:

1. Get the MailBuilder
2. Set the subject
3. Set the text message
4. Add a recipient
5. Possibly add another recipient
6. Possibly set the from address
7. Possibly add a reply-to address
8. Possibly add another reply-to address
9. Do build (+ send)

When you have built a Mail instance, you can re-use the MailBuilder to build more instances. Something like:

1. Set a new subject
2. Set a new text message
3. Clear recipients
4. Add a new recipient
5. Do build (+ send)

Example of how this strategy could be implemented in server-side JavaScript:
(send one "personalized" mail to Magnus and another one to Klas)

   // Import MailUtil in apps (WebApp, RESTApp, Widget, MCPServer etc)
   // NOTE! Use the require function instead in other server-side Javascripts (e.g. Script module), i.e:
   // const mailUtil = require("MailUtil");
   import mailUtil from "@sitevision/api/server/MailUtil";

   // Create a mail builder instance
   const mailBuilder = mailUtil.getMailBuilder();

   // Create a mail
   let mail = mailBuilder
                 .setSubject("Hello buddy")
                 .setTextMessage("How are you Magnus?")
                 .addRecipient("magnus.lovgren@sitevision.se")
                 .build();

   // Send mail
   if (mail.send()) {
       console.log("Mail to Magnus successfully sent!");
   } else {
       console.log("Mail to Magnus could NOT be sent!");
   }

   // Create another mail, with other message and recipient
   mail = mailBuilder
             .setTextMessage("How are you Klas?")
             .clearRecipients()
             .addRecipient("Klash <klas.hedstrom@sitevision.se>")
             .build();

   // Send mail
   if (mail.send()) {
       console.log("Mail to Klas successfully sent!");
   } else {
       console.log("Mail to Klas could NOT be sent!");
   }
 

Note that Velocity has some caveats when working fluently with a Builder!
It is not allowed to add whitespace between chained method calls. This is an example of how to use line breaks and indentation in Velocity when working with a Builder:

   ## Get the mail util and the mail builder
   #set ($mailUtil = $sitevisionUtils.mailUtil)
   #set ($mailBuilder = $mailUtil.mailBuilder)

   ## Create a mail
   #set ($mail = $mailBuilder.setSubject('Hello buddy'
                            ).setTextMessage('How are you Magnus?'
                            ).addRecipient('magnus.lovgren@sitevision.se'
                            ).build())
 

Tip! The Builder interface documentation contains more information about Builders and how to work with them!

An instance of the Sitevision class implementing this interface can be obtained via MailUtil.getMailBuilder(). See MailUtil for how to obtain an instance of the MailUtil interface.

Since:

Sitevision 3.6

Author:

Magnus Lövgren

Method Summary

Modifier and Type	Method and Description
MailBuilder	addBlindCopyRecipient(String aBlindCopyRecipientAddress) Adds a blind carbon copy recipient address (BCC).
MailBuilder	addCopyRecipient(String aCopyRecipientAddress) Adds a carbon copy recipient address (CC).
MailBuilder	addRecipient(String aRecipientAddress) Adds a recipient address (TO).
MailBuilder	addReplyTo(String aReplyToAddress) Adds a reply-to address.
Mail	build() Creates a Mail instance using current state of this builder.
MailBuilder	clearAllRecipients() Convenience method for removing all addresses for all recipient types (TO/CC/BCC).
MailBuilder	clearBlindCopyRecipients() Removes all previously added blind carbon copy recipient addresses (BCC).
MailBuilder	clearCopyRecipients() Removes all previously added carbon copy recipient addresses (CC).
MailBuilder	clearRecipients() Removes all previously added recipient addresses (TO).
MailBuilder	clearReplyTos() Removes all previously added reply-to addresses.
MailBuilder	setFrom(String aFromAddress) Sets the from address.
MailBuilder	setHtmlMessage(String aHtmlMessage) Sets the html message.
MailBuilder	setSubject(String aSubject) Sets the subject.
MailBuilder	setTextMessage(String aTextMessage) Sets the text message.

Method Detail

setFrom

MailBuilder setFrom(String aFromAddress)

Sets the from address.

The from address can be in basic format ("example@domain.com") or in "mailbox" format ("Some Name <example@domain.com>")

Note! Even if you explicitly set a from address, it might not be used when the mail is sent. It will only be used if it is valid and the domain part of the address is also matching the DKIM signing domain (if DKIM is setup).

If no from address is set or the from address is invalid or the domain part of the address is not matching the DKIM signing domain, the most appropriate address from the site (or server) will be used instead.

Parameters:

aFromAddress - the from address. A whitespace-only address will be ignored, default (null) will be set instead.

Returns:

this builder

addReplyTo

MailBuilder addReplyTo(String aReplyToAddress)

Adds a reply-to address.

The reply-to address can be in basic format ("example@domain.com") or in "mailbox" format ("Some Name <example@domain.com>")

Parameters:

aReplyToAddress - a reply-to address. A null or whitespace-only address will be ignored.

Returns:

this builder

clearReplyTos

MailBuilder clearReplyTos()

Removes all previously added reply-to addresses.

Returns:

this builder

setSubject

MailBuilder setSubject(String aSubject)

Sets the subject.

Parameters:

aSubject - a subject

Returns:

this builder

setTextMessage

MailBuilder setTextMessage(String aTextMessage)

Sets the text message.

Parameters:

aTextMessage - a text message

Returns:

this builder

setHtmlMessage

MailBuilder setHtmlMessage(String aHtmlMessage)

Sets the html message.

Parameters:

aHtmlMessage - a html message

Returns:

this builder

Since:

Sitevision 4.3

addRecipient

MailBuilder addRecipient(String aRecipientAddress)

Adds a recipient address (TO).

The recipient address can be in basic format ("example@domain.com") or in "mailbox" format ("Some Name <example@domain.com>")

Parameters:

aRecipientAddress - a recipient address. A null or whitespace-only address will be ignored.

Returns:

this builder

clearRecipients

MailBuilder clearRecipients()

Removes all previously added recipient addresses (TO).

Returns:

this builder

clearAllRecipients

MailBuilder clearAllRecipients()

Convenience method for removing all addresses for all recipient types (TO/CC/BCC).

Returns:

this builder

Since:

Sitevision 3.6.3

See Also:

clearRecipients(), clearCopyRecipients(), clearBlindCopyRecipients()

addCopyRecipient

MailBuilder addCopyRecipient(String aCopyRecipientAddress)

Adds a carbon copy recipient address (CC).

The carbon copy address can be in basic format ("example@domain.com") or in "mailbox" format ("Some Name <example@domain.com>")

Parameters:

aCopyRecipientAddress - a carbon copy recipient address. A null or whitespace-only address will be ignored.

Returns:

this builder

Since:

Sitevision 3.6.3

clearCopyRecipients

MailBuilder clearCopyRecipients()

Removes all previously added carbon copy recipient addresses (CC).

Returns:

this builder

Since:

Sitevision 3.6.3

addBlindCopyRecipient

MailBuilder addBlindCopyRecipient(String aBlindCopyRecipientAddress)

Adds a blind carbon copy recipient address (BCC).

The blind carbon copy address can be in basic format ("example@domain.com") or in "mailbox" format ("Some Name <example@domain.com>")

Parameters:

aBlindCopyRecipientAddress - a blind carbon copy recipient address. A null or whitespace-only address will be ignored.

Returns:

this builder

Since:

Sitevision 3.6.3

clearBlindCopyRecipients

MailBuilder clearBlindCopyRecipients()

Removes all previously added blind carbon copy recipient addresses (BCC).

Returns:

this builder

Since:

Sitevision 3.6.3

build

Mail build()
    throws IllegalStateException

Creates a Mail instance using current state of this builder.

Specified by:

build in interface Builder<Mail>

Returns:

a mail that can be sent

Throws:

IllegalStateException - will be thrown if subject is null, if there are no recipients or if a recipient address is invalid, if the from address, a copy address, blind copy address or reply-to address is invalid.