16.7 Managing Email Templates

Enable users to send emails from your application by creating email templates.

Note:

Before you can send email from an application, your Instance administrator must sign in to Oracle APEX Administration Services, navigate to the Instance Settings page and configure Email attributes.

• Defining an Email Template
  Define email templates for your application. Email templates include both an HTML Format and a Plain Text Format.
• Viewing Sample Email Templates
  View the sample email templates: Load Order Details, Load Event Reminder, or Load Scheduled Outage.
• About Including Dynamic Text
  Provide dynamic text in your email templates using existing substitution modifiers.
• Editing or Deleting Email Templates
  Edit or delete existing email templates.
• Copying an Email Template
  Copy existing email templates.

See Also:

• Sending Email from an Application
• Configuring Email in Oracle APEX Administration Guide
• APEX_MAIL in Oracle APEX API Reference

16.7.1 Defining an Email Template

Define email templates for your application. Email templates include both an HTML Format and a Plain Text Format.

To define an email template:

1. Navigate to the Shared Components page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components.
      The Shared Components page appears.
2. Under Other Components, select Email Templates.
3. On the Email Templates page, click Create Email Template.
   The Details page appears.

   Tip:

   To get started, review the sample email templates available under Sample Templates on the right side of the page. To load a sample email template, simply select it. See Viewing Sample Email Templates.
4. Next, define your template.

   Tip:

   For Email Subject, HTML Format or Plain Text Format, insert substitution strings using the format #STRING_NAME#. You can pass in values for these strings using the Placeholder Values dialog for the process in Page Designer or the APEX_MAIL API.

5. Under Identification:
   1. Template Name - Enter a descriptive name for this template.
   2. Static Identifier - Static string identifier used to refer to the template when calling the APEX_MAIL APIs.
   3. Email Subject - Enter the text to display for the email subject. You may use substitution strings with the #STRING_NAME# format. You can pass in values for these strings using Placeholder Values dialog for the process in Page Designer or the APEX_MAIL API.
6. Under HTML Format:

   Tip:

   You may use substitution strings with the #STRING_NAME# format. You can pass in values for these strings using the Placeholder Values dialog for the process in Page Designer or the APEX_MAIL API.
   1. Header - Define the Header.
   2. Body - Define the Body. You can use basic markup to format the body of your HTML email.
   3. Footer - Define the Footer.
   4. Advanced, HTML Template - See item Help for a list of supported substitution strings.
   5. (Optional) Click Load Default HTML. The default HTML appears in the HTML Template. If needed, edit the default HTML Template.
7. Plain Text Format - Enter the appropriate template defaults. You may use substitution strings with the #STRING_NAME# format. You can pass in values for these strings using the Placeholder Values dialog for the process in Page Designer or the APEX_MAIL API.
8. (Optional) Comments - Enter comments that describe this template.
9. Click Create Email Template.

Next, create a button and process to call the APEX_MAIL API.

10. Add a Send Mail button:
    1. Return to the application from which you want to send email.
    2. Navigate to the appropriate page or create a new page.
    3. In Page Designer, add a button to send the email.
    4. Create a Process of the Identification, Type: Send E-Mail.
       The Settings field displays configuration fields for sending email.
    5. Complete the required fields. Address fields (To, Cc, Bcc, Reply To) can contain substitution strings in the format &P2_CUST_EMAIL. (include the period).
11. Do one of the following:

    • Apply the Email Template

      Under Settings, Email Template, select the template you defined earlier.

      (Optional) Click the Placeholder Values button to open the Set Placeholder Values dialog. This dialog shows all placeholders defined in the Email Template and enables you to assign a static value or the value of a page or application item to it. In the dialog, click the LOV icon right to the "Item or Value" input field to pick a page item.

    • Apply a PL/SQL Process

      Create a PL/SQL process which calls the APEX_MAIL API.

      Consider the following example:

      begin
          apex_mail.send (
              p_to                 => '[e-mail]',
              p_template_static_id => 'ORDER_CONFIRMATION',
              p_placeholders       => q'~
              {
                  "CUSTOMER_NAME": "Steven King",
                  "ORDER_NUMBER": 1234,
                  "ORDER_DATE": "02-Feb-2018",
                  "SHIP_TO": "Steven King",
                  "SHIPPING_ADDRESS_LINE_1": "2004 Charade Rd",
                  "SHIPPING_ADDRESS_LINE_2": "Seattle, Washinton",
                  "ITEMS_ORDERED": 3,
                  "ORDER_TOTAL": "$ 1,200.99",
                  "ORDER_URL": "http://domain/apex/f?p=&APP_ID"        
               }~' );
          apex_mail.push_queue;
      end;

12. Save the page.
13. Run the page and click the Send Mail button.

See Also:

• Managing Pages in an Application
• Managing Buttons
• Understanding Page Processes
• APEX_MAIL in Oracle APEX API Reference

16.7.2 Viewing Sample Email Templates

View the sample email templates: Load Order Details, Load Event Reminder, or Load Scheduled Outage.

To view sample email template:

1. Navigate to the Shared Components page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components.

      The Shared Components page appears.

2. Under Other Components, select Email Templates.
3. On the Email Templates page, click Create Email Template.
   The Details page appears.
4. On the right side of the page, find the Sample Templates region.
   The Sample Templates region contains three templates:

   • Load Order Details

   • Load Event Reminder

   • Load Scheduled Outage

5. Select a template. For example, select Load Order Details.
   The template appears.
6. Expand the Sample API Usage region at the bottom of the page to see an example. The following is the Load Order Details API example.

   begin
       apex_mail.send (
           p_to                 => email_address_of_user,
           p_template_static_id => '',
           p_placeholders       => '{'
           '    "CUSTOMER_NAME":'           || apex_json.stringify( some_value )
           '   ,"ITEMS_ORDERED":'           || apex_json.stringify( some_value )
           '   ,"MY_APPLICATION_LINK":'     || apex_json.stringify( some_value )
           '   ,"ORDER_DATE":'              || apex_json.stringify( some_value )
           '   ,"ORDER_NUMBER":'            || apex_json.stringify( some_value )
           '   ,"ORDER_TOTAL":'             || apex_json.stringify( some_value )
           '   ,"ORDER_URL":'               || apex_json.stringify( some_value )
           '   ,"SHIPPING_ADDRESS_LINE_1":' || apex_json.stringify( some_value )
           '   ,"SHIPPING_ADDRESS_LINE_2":' || apex_json.stringify( some_value )
           '   ,"SHIP_TO":'                 || apex_json.stringify( some_value )
           '}' );
   end;

7. See Defining an Email Template for information edting attributes, creating a template, and creating a Send Mail button.

16.7.3 About Including Dynamic Text

Provide dynamic text in your email templates using existing substitution modifiers.

Note:

Template directives are supported by specific attributes of email templates. See Using Template Directives.

For security reasons, the values substituted for the placeholders (#NAME#) in the email templates are automatically escaped based on the context. In other words, HTML formatted templates include HTML escaping and Plain Text templates do not. If this is not the desired behavior for your environment, you can provide dynamic text which contains HTML tags using the existing substitution modifiers:

• #NAME!RAW# - Text is substituted as is.

• #NAME!STRIPHTML# - All HTML tags are removed.

Extending the Email Templates

For example, you can extend the HTML Format - Body template with:

<tr>
        <th align="left">Additional Information</th>
        <td>#ADDITIONAL_INFO!RAW#</td>
</tr>

Similarly, you can extend the Plain Text Format template with:

  Additional Info:  #ADDITIONAL_INFO!STRIPHTML#

Sample PL/SQL

The PL/SQL code would look similar to this:

begin
    apex_mail.send (
        p_to                 => '[e-mail]',
        p_template_static_id => 'ORDER_CONFIRMATION',
        p_placeholders       => q'~
        {
            "CUSTOMER_NAME": "Steven King",
            "ORDER_NUMBER": 1234,
            "ORDER_DATE": "02-Feb-2018",
            "SHIP_TO": "Steven King",
            "SHIPPING_ADDRESS_LINE_1": "2004 Charade Rd",
            "SHIPPING_ADDRESS_LINE_2": "Seattle, Washinton",
            "ITEMS_ORDERED": 3,
            "ORDER_TOTAL": "$ 1,200.99",
            "ORDER_URL": "http://domain/apex/f?p=&APP_ID" 
               "ADDITIONAL_INFO": "We plan to deliver your ordered items <strong>tomorrow morning between 08:00 and 09:00</strong>       
         }~' );
    apex_mail.push_queue;
end;

16.7.4 Editing or Deleting Email Templates

Edit or delete existing email templates.

To edit or delete an email template:

1. Navigate to the Shared Components page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components.

      The Shared Components page appears.

2. Under Other Components, select Email Templates.
   The Email Templates page appears.
3. To edit an email template:
   1. Click the email template name.
      The Template Details appear.
   2. Edit the appropriate attributes.
   3. Click Apply Changes.
4. To delete an email template:
   1. Click the email template name.
      The Template Details appear.
   2. Click Delete.
   3. Confirm your selection and click Delete.

16.7.5 Copying an Email Template

Copy existing email templates.

To copy an email template:

1. Navigate to the Shared Components page:
   1. On the Workspace home page, click App Builder.
   2. Select an application.
   3. On the Application home page, click Shared Components.

      The Shared Components page appears.

2. Under Other Components, select Email Templates.
   The Email Templates page appears.
3. Click Copy.
   The Copy Email Template Wizard appears.
4. Copy Email Template:
   1. Copy From - Select where to copy the email template from. Options include:

      • This Application

      • Other Application

   2. Application - This option only displays if Copy From is set to Other Application. Choose the application to copy the email template from.
   3. Copy Email Template - Choose an email template to copy.
   4. New Name - Enter a name for the new email template.
   5. New Static Identifier - Provides a unique static identifier for the copied email template.
   6. Click Copy Email Template.