View source for HowTo:Send Messages to Multiple Recipients

<noinclude>{{Orientation | Designers | Beginner | 15}}</noinclude>
There are many ways to send a single message to multiple recipients. This writeup summarizes the possibilities so you can choose the mechanism that is most appropriate for your application.

===User-Controlled===
:When sending an email from a [[Case]] or from any other record in the system, a user can add as many recipients as they like.
:'''Advantage:''' Infinite flexibility
:'''Disadvantage:''' Requires manual effort that becomes excessive when duplicated my different users and/or repeated by the same user.
:''Learn more:'' [[Working_with_Cases#Respond to a Case or Add a Note|Respond to a Case or Add a Note]]

===Template-Controlled Addresses===
:When creating an [[Email Template]], a comma-separated list of recipients can be specified.
:[[Rules]] and [[Processes]] can then be used to send a message using that template. (Or for records other than [[Case]] records, the template to use can be selected by the user.)
:There are multiple ways to do it:
::* Individual recipient addresses can be hard-coded into the <tt>To</tt>, <tt>Cc</tt>, or <tt>Bcc</tt> fields.
::* [[Template Variables in Email Templates|Template Variables]] can reference [[Lookup]] fields in the record to include email addresses from related [[Contacts]] and [[Users]].
:'''Advantage:''' Addresses can be taken from related Contacts and User records
:'''Disadvantage:''' Each value is a single address, which is fine unless you need to send to a list or recipients.

===List of Addresses in a Record===
: An [[Email Address field]] can be added to the object. For a given record, that field can contain a single email address or a comma-separated list of addresses. That email field can then used as a template variable in one of the template lists.
:'''Advantage:''' Every record can have it's own unique set of addresses.
:'''Disadvantage:''' Address values have to be added to every record.

===Multiple Send Message Actions in Rule or Process===
: A [[Rule]] or [[Process]] can perform multiple actions, and each action can use a template to send a message using an [[Email Address field]] either in the record, or in a related record.
:'''Advantage:''' The same template can be used with different sets of recipients.
:'''Disadvantage:''' Each recipient gets their own copy of the message. They can't see who else got it, or engage in an email conversation with the other recipients.

===List of Addresses in a Related Record===
: Sometimes, an object already contains a Lookup to an object that could be augmented with an email list. For example, if each incoming Case were assigned to an specific ''Department'' using a record that gave the name and telephone number of the department manager, then an [[Email Address field]] could be added to the Department object, and that value could be used as a variable in the Email Template.
:'''Advantage:''' Every record is automatically associated with the appropriate list.
:'''Disadvantage:''' Requires a related object that will always be targeted by a Lookup, when records are processed.

===Using an External "Alias"===
: One or more of the addresses contained in an email field could also be an ''email alias''--a list of email addresses maintained on a separate server.
:'''Advantage:''' Ability to re-use a list that is already being maintained elsewhere. 
:'''Disadvantage:''' In general, this technique works only for an [[On-Premise Installation]].
:: Because an email alias is generally maintained on an [[LDAP Server]], and that server is typically deployed behind a firewall, for protection.

===Using an "Internal Alias"===
:At this point, we've learned that an email address field can contain a comma-separated list of addresses. And we know that [[Contacts]] and [[User]] records (for example), contain an email address field.

:Putting those two ideas together creates a third possibility: Create a "User" record who's email "address" is in actuality a list of addresses. Then:
::* That "user" could be specified as a recipient in a template.
::* It could be selected from a [[Rule]] or [[Process]] (assuming that there is a Lookup field that points to it).
::* The field value could be accessed programmatically, using a technique that will be described momentarily.

===Store Addresses in a Configuration Object===
:As an example, you could create an object called '''Notifications'' that has two fields:
::* '''Category''' - a name you use to designate the kind of notification you are doing.
::* '''Recipients''' - An [[Email Address field]] that contains a single email address or a comma-separated list of addresses. (Or even email aliases, for an On-premise Installation.)

:You can then use [[Rules]] and [[Processes]] to send an Email, specifying a template that uses the recipient-list specified by a given record. 

:'''Advantage:''' Highly flexible. Recipients can be changed by editing a record, rather than modifying a template. A list can be used in multiple templates.
:'''Disadvantage:''' Requires setting up a configuration object.

===Retrieve Addresses Programmatically===
:Using any of the previously-mentioned internal storage mechanisms for a list of email addresses, you can programmatically access that list and use the Java [[sendEmail]] or [[sendEmailUsingTemplate]] API to send a message to it.

:This approach goes beyond the beginner stage, of course. But it's worth knowing that it exists--either to get someone more experienced involved, or to consider it for an initial project to begin honing your development skills.

:Here's the kind of Java [[Class]] you'll need to write:
::<syntaxhighlight lang="java" enclose="div">
package com.platform.{YOURDOMAIN}.util;

import com.platform.api.*;

public class UtilityFunctions
{
   // Send a message to a "user" who happens to contain a list of email addresses
   public void sendMessage(Parameters p) throws Exception
   {
      // Get the ID of the current object and record
      String objectID = p.get("object_id");
      String recordID = p.get("id");  

      // Get the address list
      String userID = "USER_RECORD_ID_GOES_HERE";
      Result result = Functions.getRecord("USER", "email", userID);
      if(result.getCode() < 0) {  
         String msg = "Error accessing user alias.\n"; 
         Logger.info(msg + result.getMessage(), "UtilityFunctions");
         Functions.throwError(msg);
      }
      Parameters resultParams = result.getParameters();
      String userList = resultParams.get("email");

      // Send the message
      String subject = "PUT SUBJECT HERE";
      String message = "PUT MESSAGE HERE";
      result = Functions.sendEmail(objectID, recordID, userList, "", 
                                   subject, message, "", "");
      if(result.getCode() < 0) {  
         String msg = "Error sending message.\n"; 
         Logger.info(msg + result.getMessage(), "UtilityFunctions");
         Functions.throwError(msg);
      }
      Functions.showMessage("email has been sent");
   }
}
</syntaxhighlight>

:'''Advantage:''' Ultimate flexibility.
:'''Disadvantage:''' Requires a small amount of code and the "wiring" to invoke it.

:''Learn more:'' [[Java Code Samples#Send an Email Message]]

===Wrap Up===
:At this point, you've seen a number of ways to send a message to a list of users, along with the advantages and disadvantages of each approach. You should now be able to pick the approach that will work best for your application. 
<!--
  No category for a HowTo Guide.
  They're reached from the index page in the Nav Bar.
  No point having an entry in the categories list, as well.
-->