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 log in to Oracle Application Express 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.

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, support substitution strings using the format #STRING_NAME# . You can pass in values for these strings using 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.
  6. Under HTML Format:
    1. Define the Header, Body, and Footer. Body supports basic HTML markup.
    2. Under Advanced, optionally click Load Default HTML.
      The default HTML appears in the HTML Template. If needed, edit the default HTML Template.
  7. Under Plain Text Format, enter the appropriate template defaults.
  8. Under Comments, optionally 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. Add a button to send the email.
    4. 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;
    5. Run the page and click the Send Mail button.

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;

About Including Dynamic Text

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

For security reason, 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>
        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;

Editing 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.
    2. Edit the appropriate attributes.
    3. Click Apply Changes.
  4. To delete an email template:
    1. Click the email template name.
    2. Click Delete.