Previous Next JavaScript must be enabled to correctly display this content

## 16.12 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 or Subscribing to an Email Template
  Copy an email template from the current application or from another application. When copying an email template from another application, you can also subscribe to it.
- Subscribing to Email Templates
  Subscribe to email templates on the Email Templates, Details page.
- Accessing Email Template Reports
  View the email template Utilization and History reports by clicking the appropriate tab on the Email Templates page.

See Also:

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

Parent topic: Managing Shared Components

### 16.12.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 User Interface, select Email Templates.
   The Email Templates page appears.
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                 => 'steven.king@example.com',
                  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

Parent topic: Managing Email Templates

### 16.12.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 User Interface, select Email Templates.

   The Email Templates page appears.

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.

Parent topic: Managing Email Templates

### 16.12.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                 => 'steven.king@example.com',
            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;

Parent topic: Managing Email Templates

### 16.12.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 User Interface, 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.

Parent topic: Managing Email Templates

### 16.12.5 Copying or Subscribing to an Email Template

Copy an email template from the current application or from another application. When copying an email template from another application, you can also subscribe to it.

Tip:

Subscriptions enable developers to reuse shared components across several applications in a workspace. To learn more about subscriptions, see Using Shared Component Subscriptions.

To copy an email template:

1. Navigate to the Shared Components, Email Templates 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.

   4. Under User Interface, select Email Templates.

      The Email Templates page appears. Note that the report includes the following columns: Subscribed From, Subscription Status, and Subscribers.

2. To copy an email template within the current application:
   1. Search for the email template and click Copy in the Copy column.
      The Copy Email Template Wizard appears.
   2. New Name - Provide a name for the copied email template.
   3. New Static Identifier - Provide a unique static identifier for the copied email template.
   4. Click Copy Email Template.
3. To copy an email template from another application:
   1. From the Tasks region on the Email Templates page, click Copy from another app.
      The Copy Email Template Wizard appears.
   2. Application - Select the application from which you want to copy.
   3. Copy Email Template - Select the email template to copy.
   4. Subscribe - Enable this flag to subscribe to the email template.
   5. Click Copy Email Template.

Parent topic: Managing Email Templates

### 16.12.6 Subscribing to Email Templates

Subscribe to email templates on the Email Templates, Details page.

Subscriptions enable developers to reuse shared components across several applications in a workspace. To learn more about shared component subscriptions, see Using Shared Component Subscriptions.

Tip:

You can also subscribe to an email template by copying it and enabling the Subscribe option. See Copying or Subscribing to an Email Template.

To subscribe to email templates in the current application:

1. Navigate to the Email Templates page:
   1. Navigate to the Workspace home page.
   2. Click the App Builder icon.
   3. Select an application.
   4. On the Application home page, click Shared Components.
   5. Under Navigation and Search, click Email Templates.

      The Email Templates page appears. Note that the report includes the following columns: Subscribed From, Subscription Status, and Subscribers.

2. Select an email template.
   The Email Templates, Details page appears.
3. To subscribe to an email template:
   1. Find the Subscription region.
   2. Subscription, Subscribe From - Select a master email template to subscribe to and click Apply Changes.
   3. Confirm your selection and click Subscribe.

      The subscribed component is automatically refreshed from the selected master.

4. To refresh a subscription:
   1. Find the Subscription region.
   2. Subscription, Refresh Email Template - If the email template is already subscribed, click Refresh Email Template.
   3. Click Apply Changes.
5. To unsubscribe from an email template:
   1. Find the Subscription region.
   2. Subscription, Unsubscribe - Click Unsubscribe.

Parent topic: Managing Email Templates

### 16.12.7 Accessing Email Template Reports

View the email template Utilization and History reports by clicking the appropriate tab on the Email Templates page.

To view email template reports:

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 User Interface, select Email Templates.
   The Email Templates page appears.
3. Click the appropriate tab:
   - Utilization - Displays where email templates are used within the application.
   - History - Displays recent modifications made to email templates in this application.

Parent topic: Managing Email Templates