1/7/22, 12:14 AM Document 2428364.

1
  khaled (Available) (0) Contact Us Help
PowLast Login: January 7, 2022 12:09 AM EET Switch to Cloud Support

 
Dashboard Knowledge Service Requests Patches & Updates Community
Service Requests >
Give Feedback...

Copyright (c) 2022, Oracle. All rights reserved. Oracle Confidential.

Database Cloud Service (DBCS / DBaaS) on OCI: How to Set Up APEX_MAIL (Doc ID 2428364.1) To Bottom

In this Document   Was this document helpful?  

Goal Yes
No
Solution    

  Gather the Installation Information

  Document Details  
  Review the Configuration
  Modify the APEX Instance Settings
Type:
HOWTO
  Troubleshooting Status:
PUBLISHED
References Last Major
Aug 9, 2021
Update:
Aug 9, 2021
Last Update:

APPLIES TO:    

  Related Products  
Oracle Application Express (APEX) - Version 5.1 and later

Oracle Application Express
Oracle Cloud Infrastructure - Database Service - Version N/A and later (APEX)
Oracle Database Cloud Service - Version N/A and later
Oracle Cloud Infrastructure -
Information in this document applies to any platform.
Database Service
This document discusses how to set up APEX_MAIL in
Database Cloud Service on Oracle Cloud Infrastructure (OCI). Oracle Database Cloud Service

   

  Information Centers  
Information Center: Oracle
Application Express (APEX)
[1418083.2]

Oracle Catalog: Service

Request Data Collections
GOAL (SRDCs) for all Products and
Services [51.2]

Application Express (APEX) has been configured and is running successfully in DBaaS in Oracle Cloud Infrastructure (OCI). Oracle Catalog: Information
Centers and Advisors for All
Products and Services [50.2]
What steps are required in order to set up APEX mail using Oracle Cloud Infrastructure Email Delivery?
Platform as a Service (PaaS)
and Oracle Cloud
SOLUTION Infrastructure (OCI)
Information Center
[2048297.2]
This document discusses how to set up APEX_MAIL in Database Cloud Service on Oracle Cloud Infrastructure (OCI).
Index of Oracle Database
Information Centers
Oracle Cloud Infrastructure Classic customers should refer to Note 2079333.1 - DBaaS: Cloud Mail Notification Services [1568043.2]
Setup.

Oracle Autonomous Database (Shared Exadata Infrastructure) customers should refer to Send Email from Oracle Application
   

Express.   Document References  

How to Send Email from OCI
  DBSystem Through UTL_SMTP
[2669075.1]

Gather the Installation Information

   

  Recently Viewed  
This step discusses how to determine the current set up for the installation.
FA:SCM:INV: SQL Query to
1. Login to the VM as the opc user and switch the user to oracle. Get Employee Name From
Cycle Count Details
sudo su - oracle [2773189.1]
. oraenv

Physical Inventory - FAQ

[2257524.1]

2. Download and run the apex_verify.sql according to the instructions in Note 1254932.1 - APEX Installation Verification Script in AP Invoice Approval
Workflow: Absolute Value Of
order to get a snap shot of the current APEX configuration. Invoice Header Amount
[2585111.1]
alter session set container = pdb1; Need To Convert Invoice
show con_name

Amounts To USD In AP
Invoice Approvals, How To
Define An Appropriate
If unsure of the container, the execute the following query:  Approval Rule [2020649.1]
How To Personalize /
select NAME from v$containers; Customize The Content Of
An Approval Notification E-
mail? [344346.1]

https://support.oracle.com/epmos/faces/DocumentDisplay?_afrLoop=1356610189110469&parent=SrDetailText&sourceId=3-27982090861&id=242836… 1/6
1/7/22, 12:14 AM Document 2428364.1
  Show More
   

NOTE: In the example below is for demonstration purposes only. The user information and data used
represents fictitious data. Any similarity to actual data and / or persons, living or dead, is purely coincidental
and not intended in any manner.
            All steps in this document are to be executed against the PDB in a multi-tenant environment.

Review the Configuration

1. APEX_MAIL uses the database package UTL_SMTP. As a result, and ACL must be created for the APEX installation schema. For
APEX 5.1.x, the installation schema would be APEX_050100.

Check the Enabling of Network Services (11g DBs and Later) section of the apex_verify_out.html report to ensure that an entry
has been created for the APEX schema. If this entry is missing, please create it according to the instructions in the APEX
installation guide.

Documentation for the current release can be found here. 

Documentation for prior releases can be found here.

2. Determine if the email mode is set to allow mail from the SMTP server. 

 Login as the SYS user. If using a 12c database, switch containers to the PDB where APEX is installed, and run the
following commands:

  
alter session set current_schema = apex_050100;

select wwv_flow_platform.get_preference( p_preference_name => 'SMTP_REST_EMAIL_MODE') from dual;

If the value returned is 'Y', reset it to 'N' as follows: 

begin

wwv_flow_platform.set_preference( p_preference_name => 'SMTP_REST_EMAIL_MODE', p_preference_value

=> 'N');
commit;
end;

3. Determine if a wallet is being used by the APEX instance. If not, create the wallet.

alter session set current_schema = apex_050100;

select apex_instance_admin.get_parameter( p_parameter => 'WALLET_PATH') from dual;

If an entry is returned, make sure that you have the wallet password. This will be needed for adding the SMTP server Root
and intermediate certificates to your wallet.

If an entry is not returned and there is no other database wallet used by the database applications, you can create a wallet
as follows:

orapki wallet create -wallet /home/oracle/wallet -pwd WALLET_PASSWORD -auto_login

4. Identify the required related mail users:

Identity Domain ocid user for the DBaaS resource:

https://docs.cloud.oracle.com/iaas/Content/General/Concepts/identifiers.htm > Where to Find Your Tenancy's OCID
For this example, the user is: ocid1.tenancy.oc1..<variouslettersandnumbers>

If an SMTP user does not exist, see the following documentation for creating the SMTP user within IDCS:
https://docs.cloud.oracle.com/iaas/Content/Email/Tasks/generatesmtpcredentials.htm

a. Create a new user to act as the SMTP user according to the documentation above.

b. Once the new SMTP user has been created, generate the SMTP user credentials according to
https://docs.cloud.oracle.com/iaas/Content/Email/Tasks/generatesmtpcredentials.htm

SMTP approved sender: https://docs.cloud.oracle.com/iaas/Content/Email/Tasks/managingapprovedsenders.htm?

tocpath=Services|Email Delivery|_____2

For this example, the SMTP approved sender is testing@example.com

  

https://support.oracle.com/epmos/faces/DocumentDisplay?_afrLoop=1356610189110469&parent=SrDetailText&sourceId=3-27982090861&id=242836… 2/6
1/7/22, 12:14 AM Document 2428364.1

An error ORA-29279: SMTP permanent error: 535 Authorization failed: Envelope From address will appear if the mail id is not
added as part of the approved sender

Note: Depending on the configuration, it may be necessary to define an egress rule from the subnet where DBCS is
provisioned to Email Delivery IP (/32 CIDR) for destination port 587 using TCP protocol. A Service Gateway or NAT Gateway
route may also be required in this subnet.

  

Modify the APEX Instance Settings

1. Add the SMTP server intermediate and root certificates to the database wallet.

Download the SSL Root and Intermediate Certificates (.crt format) directly from here

Root Certificate - DigiCert Global Root G2

Intermediate Certificate - DigiCert Global G2 TLS RSA SHA256 2020 CA1

From the VM command line as the oracle user (assuming the .crt files are in /home/oracle/wallet):
orapki wallet add -wallet /home/oracle/wallet -trusted_cert -cert
"/home/oracle/wallet/DigiCertGlobalRootCA.crt" -pwd WALLET_PASSWORD
orapki wallet add -wallet /home/oracle/wallet -trusted_cert -cert

"/home/oracle/DigiCertSHA2SecureServerCA.crt" -pwd WALLET_PASSWORD

 
To
view the certificates in the wallet:
orapki wallet display -wallet /home/oracle/wallet -pwd WALLET_PASSWORD
 

 2. Modify the APEX instance settings.

Login to the APEX admin page and go to Manage Instance > Instance Settings

Add the wallet name and wallet password:

The format is file:/home/oracle/wallet

3. Modify the APEX Mail Server settings:

SMTP Host address: smtp.us-phoenix-1.oraclecloud.com

SMTP Host Port: 587

SMTP Authentication
Username: ocid1.tenancy.oc1..<variouslettersandnumbers>
SMTP Authentication Password: <SMTP Authentication Username Password>

Check the checbox : "Check to confirm you wish to change the password"

Use SSL/TLS: After connection is established

Default Email From Address: testing@example.com

Note:

The example uses SMTP server / port information for smtp.us-phoenix-1.oraclecloud.com. Please use
the appropriate host for your service.

See: https://docs.cloud.oracle.com/iaas/Content/Email/Tasks/configuresmtpconnection.htm
Use SSL / TLS must be set to "After connection is established", which is the equivalent of UTL_SMTP.STARTTLS(c); in
the UTL_SMTP test code listed in the Troubleshooting section. If this is not set properly, you will see the following
error when running APEX_MAIL:
"ORA-29019: The protocol version
is incorrect."

  

4. Test APEX_MAIL. From SQL Commands in APEX SQL Workshop, run the following command being sure to replace the
placeholders in bold:

begin

apex_mail.send(

p_to => 'testing@example.com',

p_from => 'some_user@example.com', p_subj => 'Test from APEX',

p_body => 'Test from APEX SQL Workshop');

apex_mail.push_queue;

end;

https://support.oracle.com/epmos/faces/DocumentDisplay?_afrLoop=1356610189110469&parent=SrDetailText&sourceId=3-27982090861&id=242836… 3/6
1/7/22, 12:14 AM Document 2428364.1
 

You should receive an email in your inbox in a couple of minutes. To view the progress, select all rows from the
APEX_MAIL_QUEUE.

select * from APEX_MAIL_QUEUE;

Troubleshooting

The mail functionality is implemented in APEX using the UTL_SMTP package. The first step is to verify that he equivalent
UTL_SMTP call works when logged into SQLPlus.

1. Login to the VM as the opc user and switch the user to oracle.

sudo su - oracle
. oraenv

2. Login to the database as the SYS using SQLPlus.

To verify that you are connected to the PDB, issue the following command:

show con_name

If necessary, wwitch to the PDB that contains the APEX installation:

alter session set container = pdb1;

show con_name

3. Modify the following code to reflect: 

The OCID resource id and password

The SMTP approved sender and mail server. For this example, the SMTP mail server is:  smtp.us-phoenix-
1.oraclecloud.com, and the sender is testing@example.com. 
The database wallet defined in the APEX instance settings. In this example, the wallet is file:/home/oracle/wallet.
The email recipient of the test message. This should not be an Oracle (@oracle.com) email address. 

set serveroutput on
DECLARE

c utl_smtp.connection;

:= 'ocid1.tenancy.oc1..<variouslettersandnumbers>';
user_name VARCHAR2(254)
user_pwd VARCHAR2(64) := '<OCID_RESOURC_PASSWORD>';

PROCEDURE send_header(name IN VARCHAR2, header IN VARCHAR2) AS

BEGIN

UTL_SMTP.WRITE_DATA(c, name || ': ' || header || UTL_TCP.CRLF);

END;

BEGIN

dbms_output.put_line('mail test pdb DBAASMAIL');

c := utl_smtp.open_connection(

host => 'smtp.us-phoenix-1.oraclecloud.com',

port => 587,

wallet_path

=> 'file:/home/oracle/wallet',
wallet_password => '<WALLET_PASSWORD>',

secure_connection_before_smtp => FALSE);

UTL_SMTP.EHLO(c,'oraclecloud.com');

UTL_SMTP.STARTTLS(c);

UTL_SMTP.EHLO(c,'oraclecloud.com');
UTL_SMTP.AUTH(

c => c,

=> user_name,
username
password => user_pwd,

schemes => utl_smtp.all_schemes);

utl_smtp.mail(c, ' testing@example.com ');

utl_smtp.rcpt(c, 'some_user@example.com');

utl_smtp.open_data(c);

send_header('From', '"Testing" <testing@example.com>');

send_header('To', '"example" <someuser@example.com>');

send_header('Subject', 'Test from utl_smtp - DBAASMAIL');

UTL_SMTP.WRITE_DATA(c, UTL_TCP.CRLF || 'Hello, world!');

UTL_SMTP.CLOSE_DATA(c);

UTL_SMTP.QUIT(c);

exception when others then

in the anonymous plsql block: '|| sqlerrm);
dbms_output.put_line('Error
END;

https://support.oracle.com/epmos/faces/DocumentDisplay?_afrLoop=1356610189110469&parent=SrDetailText&sourceId=3-27982090861&id=242836… 4/6
1/7/22, 12:14 AM Document 2428364.1

 Make sure to run using set serveroutput on to get any underlying errors should the request fail.

4. Run the code above as the SYS user. Address any errors that appear.

5. Once the code above works as SYS, switch to the APEX installation user and retest the same code. For this example APEX is
5.1.4, and the APEX installation user is APEX_050100. 

alter set session set current_schema = APEX_050100;

Address any errors.

6. Once the same code is working as the APEX installation user. Login to APEX and retest the code in SQL Workshop.

Depending on the ACL set up, an additional ACL may be required for the workspace parsing schema. Below is an example of the
code used in an internal instance for the parsing schema of DBAASMAIL:

BEGIN

DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
host => '*',

ace => xs$ace_type(privilege_list => xs$name_list('connect'),

principal_name => 'DBAASMAIL',

principal_type => xs_acl.ptype_db));

END;

COMMIT;

Once the SMTP based emails are working using the sample code above as SYS, APEX_NNNNNN and as the parsing schema user
from SQLPlus, APEX_MAIL should work.

In order to validate the email configuration from Apex, the following procedure
APEX_INSTANCE_ADMIN.VALIDATE_EMAIL_CONFIG can be used

ALTER SESSION SET CURRENT_SCHEMA = APEX_200200;

BEGIN

   APEX_INSTANCE_ADMIN.VALIDATE_EMAIL_CONFIG;
END;

  

The procedure APEX_INSTANCE_ADMIN.VALIDATE_EMAIL_CONFIG is introduced beginning from the Apex Version 19.2 is to
establish a connection with the email server configured in an Application  Express instance. An error is returned if the
connection is unsuccessful. This can indicate incorrect SMTP instance parameters, missing Network ACL, missing SSL
certificate in Oracle Wallet, or a problem on  the email server side. Correct the instance configuration and re-execute this
procedure to confirm.

  

This procedure exits if the connection was successfully established.

REFERENCES

NOTE:2669075.1 - How to Send Email from OCI DBSystem Through UTL_SMTP

Didn't find what you are looking for? Ask in Community...

Related
Products

Middleware > Developer Tools > Database & PLSQL > Oracle Application Express (APEX) > Administration
Oracle Cloud > Oracle Platform Cloud > Oracle Cloud Infrastructure - Database Service > Oracle Cloud Infrastructure - Database Service > Cloud Toolset > APEX or other tools in
DB Schema Service
Oracle Cloud > Oracle Platform Cloud > Oracle Database Cloud Service > Oracle Database Cloud Service > Cloud Toolset > Application Express

Keywords
ACE; ACL; ADMIN; APEX; AUTHENTICATION; CLOUD; EMAIL; MAIL SERVER; MESSAGE; ORAPKI; PDB; UTL_SMTP; WALLET
Errors
ORA-29278

https://support.oracle.com/epmos/faces/DocumentDisplay?_afrLoop=1356610189110469&parent=SrDetailText&sourceId=3-27982090861&id=242836… 5/6
1/7/22, 12:14 AM Document 2428364.1

Back to Top
 
Copyright (c) 2022, Oracle. All rights reserved. Legal Notices and Terms of Use Privacy Statement
   

https://support.oracle.com/epmos/faces/DocumentDisplay?_afrLoop=1356610189110469&parent=SrDetailText&sourceId=3-27982090861&id=242836… 6/6