1. App Builder User's Guide
  2. Managing Shared Components
  3. Managing Email Templates

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.

See Also:

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.

  1. 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).
  2. 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;
  3. Save the page.
  4. Run the page and click the Send Mail button.

See Also:

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