Introduction
Setting up SMTP configuration in Oracle APEX is essential for enabling your applications to send emails reliably. However, issues can arise from incorrect settings, blocked ports, authentication errors, or provider-specific security policies. Troubleshooting these problems requires a methodical approach—verifying credentials, testing connectivity, and reviewing APEX logs—to identify and resolve the root cause efficiently.
Authentication Errors:
Ensure that the SMTP username and password are correct.
If using Gmail or Yahoo, create an app-specific password if two-factor authentication is enabled.
Connection Errors:
Check if the SMTP server is reachable.
Verify the correct port and encryption settings (SSL/TLS).
Emails Not Being Delivered:
Ensure the From Address is approved for sending.
Check spam filters and email logs.
Review APEX_MAIL_QUEUE for pending messages:
SELECT mail_id, sent_date, to_address, status FROM APEX_MAIL_QUEUE;
Gmail/Outlook Blocking the Email:
Enable "Less Secure Apps" if necessary (not recommended for production).
Ensure the SMTP credentials match the allowed senders in email provider settings.
Each mailbox provider has its own SMTP settings that must be configured correctly to allow Oracle APEX to send emails. By understanding the different configurations required for Gmail, Outlook, Yahoo, and OCI Email Delivery, developers can ensure smooth email transmission in their APEX applications.
Proper SMTP setup ensures that emails are delivered efficiently and securely, reducing the risk of failed or blocked messages.
Troubleshooting SMTP configuration issues in Oracle APEX involves checking several components that work together to enable successful email delivery. If APEX emails are not being sent or received, the cause could lie in incorrect settings, authentication failures, blocked network ports, or missing permissions. Below is a detailed, step-by-step approach to identify and resolve SMTP-related problems.
1. Verify Basic SMTP Settings in APEX
Navigate to Manage Instance > Instance Settings > Email or the corresponding workspace settings.
Check the following fields:
-
SMTP Host Address – Confirm this is the correct mail server address (e.g.,
smtp.gmail.com,smtp.office365.com, orsmtp.email.us-ashburn-1.oci.oraclecloud.com). -
SMTP Port – Common ports are
587(TLS),465(SSL), or25(no encryption). Use the correct one as per your provider’s documentation. -
Username – Ensure the full email address is entered if required.
-
Password – Confirm it's accurate and up to date. If using app-specific passwords (e.g., Gmail or Yahoo), use that instead of the account password.
-
Security (SSL/TLS) – Match the port you’ve chosen with the correct encryption type.
2. Test Network Connectivity
Ensure that the database server where Oracle APEX is installed can connect to the external SMTP server. From the OS or network layer:
-
Use tools like
telnet smtp.server.com 587oropenssl s_client -connect smtp.server.com:465(depending on your DB OS access). -
If the server cannot reach the SMTP endpoint, work with your network or firewall team to open the necessary ports.
3. Review Error Logs and Views
Oracle APEX provides two important views for diagnosing mail issues:
-
APEX_MAIL_LOG– Displays results of email send attempts including success or failure messages. -
APEX_MAIL_QUEUE– Shows pending emails that have not yet been pushed or sent.
Example SQL:
SELECT * FROM APEX_MAIL_LOG ORDER BY SENT_DATE DESC;
SELECT * FROM APEX_MAIL_QUEUE;
Look for error messages like:
-
Connection timed out
-
Authentication failed
-
Sender address rejected
-
Invalid credentials
4. Check Email Address Consistency
Make sure:
-
The p_from address used in
APEX_MAIL.SENDmatches the one approved by your SMTP provider. -
Some providers require the sender email to be the same as the authenticated user (especially Gmail, OCI Email Delivery, Office 365).
-
Approved sender domains are set correctly if using OCI Email Delivery.
5. Test Sending an Email
Use the following PL/SQL block to test sending:
BEGIN
APEX_MAIL.SEND(
p_to => 'your@email.com',
p_from => 'approved@sender.com',
p_subj => 'SMTP Test',
p_body => 'This is a test email sent from Oracle APEX.'
);
APEX_MAIL.PUSH_QUEUE;
END;
Then check APEX_MAIL_LOG to verify delivery status.
6. Re-check Authentication Requirements
Different SMTP providers have unique authentication rules:
-
Gmail – Requires OAuth or app passwords with 2FA enabled.
-
Office 365 – Requires SMTP AUTH to be enabled and MFA compliance.
-
OCI Email Delivery – Uses generated SMTP credentials and approved sender lists.
If these are not set up properly, authentication will fail even if credentials look correct.
7. Consider Message Content Filters
Some SMTP services reject emails with:
-
Empty subject or body
-
Invalid HTML formatting
-
Suspicious links or keywords
-
Unencoded attachments
Send a minimal test message first before testing formatted content or attachments.
8. Resend Failed Emails (Optional)
If emails failed to send due to a temporary issue (e.g., network failure), they may still be in the mail queue. Re-run:
BEGIN
APEX_MAIL.PUSH_QUEUE;
END;
This manually pushes queued emails for retry.
9. Work with Your SMTP Provider
If errors persist and logs show rejections or blacklisting, contact your email provider. Share log excerpts to get insight into what’s going wrong (e.g., spam policy violations, throttling, IP restrictions).
Summary of Common Causes and Fixes
-
Wrong port or encryption → Match port 587 with TLS, 465 with SSL
-
Wrong password → Use an app-specific password if required
-
Unapproved sender → Use only verified or approved senders
-
Blocked port → Ensure firewall allows outbound SMTP connections
-
Authentication error → Confirm username/password and policy settings
With methodical checks of settings, network access, and log analysis, SMTP configuration issues in Oracle APEX can be quickly diagnosed and resolved, allowing your applications to send email reliably and securely.
Conclusion
SMTP configuration issues can prevent your APEX applications from delivering important emails, affecting workflows and user communication. By following a structured troubleshooting process—checking network access, verifying SMTP credentials, reviewing logs, and testing with known-good values—you can resolve common problems and restore email functionality. With a stable setup, you’ll ensure dependable email delivery across all your APEX applications.
