Skip to main content

Oracle APEX Email Templates

In Oracle APEX version 18.1, new feature "Email Templates" has been introduced. Before 18.1, either you have to embed html code in pl/sql code or you have to store HTML templates in one of your tables (or as html files in network share) with "substitution strings" (place holders) and then replace those "substitution strings" with actual values before sending email. If you are using latter approach, then it's easy to migrate your code to new "Email Templates" framework.

Creating Email Templates:

You can find email templates at "Shared Components > Other Components > Email Templates" section.


When you are creating new email template, you may need to fill data for below fields.

Template Name: Name you want to give to your template. It can't contain special characters. Only characters a-Z, 0-9 and spaces are allowed.

Static Identifier: Unique template name with in the application. This will be used to call the template from APEX_MAIL.SEND

Email Subject: Subject of the email. You can use substitution strings here.

Header: Header of the email. You can use substitution strings here. You can also use HTML to format the content.

Body: Main Body of the email. You can use substitution strings here. You can also use HTML to format the content.

Footer: Any footer notes to the email. You can use substitution strings here. You can also use HTML to format the content.

Advanced > HTML Template: By default, APEX uses HTML template which looks like as below


If you want to modify, you can click on "Load Default HTML" and then you can modify the template. You can also completely replace the HTML template with your own HTML. In these cases, you can use #HEADER#, #BODY# and #FOOTER# substitution strings to refer to "Header", "Body" and "Footer" content.

Plain Text Format > Content: If users are using email clients that does not support HTML content, then this content will be displayed. So if you can show your email content in plain text format, then you can write that content here. If it's not possible, then its better to put some meaningful message here, like "Please open this email from email client which supports HTML content". If you store the emails sent from your system, then you can also give link to the email using which user can see full email content online.

Comments: Developer comments for the email template.

Previewing & Using Email Templates:

Once you have created email template, you can preview your email output using APEX_MAIL.PREPARE_TEMPLATE API.

Also, if you go to email template details page, at the bottom, APEX gives you customized "Sample API Usage" code which includes your template static id and all placeholders you have used in the template. (Pretty cool, right?).

To use the template while sending email, just copy this code, replace "some_value" with actual values and replace email_address_of_user with actual email address and then you are good to go.


You may also refer APEX_MAIL.SEND for other supported parameters while using email templates.

Points to Note:

Sample Templates: There are few sample templates provided by APEX Team. You can find them on the right-side of "Template Details" page. Click on the sample template name to load the sample template and then you can modify it as per your requirement. 

Use # with caution: For e.g. if you have below html code in your template, then #000000;color:# will be considered as substitution string and it will be shown in "Sample API Usage". 

<div style="background-color:#000000;color:#111111;"> 

As alternative, you can use RGB syntax or color names for specifying colors. Or you can also define your CSS in "Advanced > HTML Template" section. However, you can skip these invalid substitution strings while calling APEX_MAIL.SEND and it does not throw any error and it will not have any impact. 

You may refer https://www.campaignmonitor.com/css/ for CSS support in email clients. 

Dynamic HTML using substitution Strings: By default, all HTML data is escaped from substitution string values. For e.g. If you pass '<span style="color:red;">data here</span>' for a substitution string, then user will get email with "span" tags. In these cases, if you want HTML to get parsed and show the text in red color, then you can use #SUBSTITUTION_STRING_NAME!RAW# in the email template.

Using Built-in Substitution Strings: Built-in Substitution Strings that support template syntax would also work in email templates. However, looks like not all of them work, but only few. For e.g. APP_IMAGES, IMAGE_PREFIX works in email templates. You no need to pass values for these substitution strings, APEX will do it for you.

Process type "Send E-Mail": This process does not support sending emails using email templates as of APEX version 20.1.

That's it for now and stay tuned for more posts on Email templates topic.

Thank you.

If you like watching videos over reading, you can watch the video here which covers several points on email templates topic.

Labels:

Comments

Post a Comment

Popular posts from this blog

Interactive Grid - Conditional Enable/Disable

In this blogpost, I am going to discuss few approaches using which we can conditionally enable/disable Interactive Grid (IG) column(s) based on other column(s) values. Note:    There is a bug  30801170  in APEX 19.2/20.1 with respect to "enable/disable" dynamic actions for IG columns. Workaround for this bug is provided at the end of this blogpost . This bug has been fixed in APEX version 20.2. Client Side Only Conditions If conditions to enable/disable are simple, then we can check those conditions easily on the client side. For e.g. let's consider IG on EMP table with following SQL Query. SELECT EMPNO, ENAME, JOB, MGR, HIREDATE, SAL, COMM, DEPTNO FROM EMP Let's consider the requirement as - Enable "Commission" column only when JOB is equals to 'SALESMAN' and disable "Commission" column in all other cases. This can be done declaratively using dynamic actions (DA) DA "Enable/Disable Commission - 1" Create DA and give it a prope...
4 comments
Read more

Interactive Grid - Bulk Operation on Selected Rows

What's the Problem? Let's say you have an IG on employee table and you want to update selected employees commission based on user's input. Ideally, it should be very simple, where you can write UPDATE statement in page process and select IG region as "Editable Region" under "Execution Options" of the page process. But, when you select rows and submit page, you can see that, this process won't get executed! The reason is  Selection of 'Row Selector' check-boxes is not considered as row-change. Thus selected rows are not submitted to server. So, is there any work around?  Yes! Luckily there are lot of JavaScript (JS) APIs available to work with IG. If you are not already aware, you can refer "APEX IG Cookbook"  or  JavaScript API Reference documentation. If we continue with above Employee IG example, when user selects IG rows, enters "Commission %" and clicks on "Update Commission" button, then we can writ...
36 comments
Read more

Interactive Grid - Process Filtered Data on Server Side

Recently one of the APEX developers has reached out to me and asked if it's possible to capture filtered rows data of the Interactive Grid on the server-side and do some processing. In APEX 20.1, there is a new API APEX_IG , using which we can achieve this. Photo by Jakub Kapusnak on Unsplash The approach is very simple and straightforward. Get the internal region id based on the Static ID given for the IG region Get the last viewed report id based on region id Open query context for the region and report using region id and report id Fetch and loop through the rows using the query context Do something with fetched rows And finally, close the query context If you have already done this for interactive reports, then you should be already aware of these steps. The only difference here is, we use APEX_IG APIs instead of APEX_IR APIs. For the demo purpose, let's Build an Interactive Grid on EMP table and let's give it a Static ID as emp Create a Textarea page item with...
1 comment
Read more