Getting Started with Email Delivery
Email Delivery provides a highly scalable, cost effective, and reliable way to send email from your applications. Email Delivery includes developer-friendly tools to quickly send application-generated email for mission-critical communications such as receipts, programmatic notifications, or password reset emails.
Email Delivery Basics
When you use Email Delivery, we become your outbound email server. If you have an existing email server, you can keep it and configure it to send through Email Delivery. The Email Delivery service will take care of the feedback loops and platform reputation automatically.
Getting Started
This topic gives guidance on how to get started with Email Delivery. For complete details about the service and its components, see Overview of the Email Delivery Service.
Email Configuration Options
You can configure Oracle Cloud Infrastructure using the Console (a browser-based interface), REST API, SDKs, CLI or Terraform.
The Email Delivery SDK is available in several programming languages. For information on installing and configuring the Oracle Cloud Infrastructure SDKs, see Developer Resources.
Examples of SDK usage can be found on GitHub, including:
The following information describes how you can configure third-party applications to send email through Email Delivery:
- Integrating Oracle Application Express with Email Delivery
- Integrating Postfix with Email Delivery
- Integrating Oracle Enterprise Manager with Email Delivery
- Integrating Mailx with Email Delivery
- Integrating Swaks with Email Delivery
- Integrating Sendmail with Email Delivery
- Integrating JavaMail with Email Delivery
- Integrating PeopleSoft with Email Delivery
- Integrating Python with Email Delivery
Sending Email
To begin sending email with Email Delivery, complete the following steps:
Simple Mail Transfer Protocol (SMTP) credentials are necessary to send email through Email Delivery. Each user is limited to a maximum of two SMTP credentials. If more than two are required, SMTP credentials must be generated that are associated with another existing user or more users must be created.
Best Practice: A security best practice is to generate SMTP credentials for a new user instead of your Console user that already has permissions assigned to it. For detailed instructions on creating a user, see Adding Users.
-
Open the navigation menu. Under Governance and Administration, go to Identity and click Users. Locate the user in the list that has permissions to manage email, and then click the user's name to view the details.
Tip
If your user does not have permissions to view or create users, you can create SMTP credentials under your user.Open the Profile menu (
) and click User Settings.
- Click SMTP Credentials.
- Click Generate SMTP Credentials.
- Enter a Description of the SMTP Credentials in the dialog box.
- Click Generate SMTP Credentials. A user name and password is displayed.
- Copy the user name and password for your records and click Close.
The new user must be assigned to a group with permissions to manage approved-senders
and suppressions
.
- Open the navigation menu. Under Governance and Administration, go to Identity and click Policies. A list of the policies in the compartment you're viewing is displayed.
- If you want to attach the policy to a compartment other than the one you're viewing, select the desired compartment from the list on the left. Where the policy is attached controls who can later modify or delete it (see Overview of Policies).
- Click Create Policy.
- Enter the following:
- Name: A unique name for the policy. The name must be unique across all policies in your tenancy. You cannot change this later.
- Description: A friendly description. You can change this later if you want to.
- Policy Versioning: Select Keep Policy Current if you'd like the policy to stay current with any future changes to the service's definitions of verbs and resources. Or if you'd prefer to limit access according to the definitions that were current on a specific date, select Use Version Date and enter that date in format YYYY-MM-DD format. For more information, see Advanced Policy Features.
Statement: Enter the following policy statement:
Allow group <group name> to use approved-senders in compartment <compartment name>
For more information about policies and policy syntax, see Policy Basics.
- Tags: If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure if you should apply tags, then skip this option (you can apply tags later) or ask your administrator.
- Click Create.
The new policy will go into effect typically within 10 seconds.
- Open the navigation menu. Under Governance and Administration, go to Identity and click Users. A list of the users in your tenancy is displayed.
- Locate the user in the list.
- Click the user. Its details are displayed.
- Click Groups.
- Click Add User to Group.
- Select the group from the drop-down list, and then click Add.
Make sure to let the user know which compartment(s) they have access to.
You must set up an approved sender for all “From:” addresses sending mail via Oracle Cloud Infrastructure or mail will be rejected. An approved sender is associated with a compartment and only exists in the region where the approved sender was configured. That is, if you create an approved sender in the Phoenix (PHX) region, you cannot send email through the Ashburn (IAD) region.
Best Practice: Approved senders should not be created in the root compartment. If approved senders exist in the root compartment, you are required to create a policy to manage approved senders in the entire tenant. Creating approved senders in a compartment other than the root allows the policy to be specific to that compartment.
-
Open the navigation menu. Under Solutions and
Platform, go to Email Delivery and click Email Approved Senders. Ensure that you are in the correct compartment. Your user must be in a group with permissions to manage
approved-senders
in this compartment. - Click Create Approved Sender within the Approved Senders view.
- Enter the email address you want to list as an approved sender in the Add Sender dialog box.
- Click Add. The email address is added to your Approved Senders list.
Approved senders are unique to tenancies. If an attempt is made to create a duplicate approved sender within a tenancy, the service will return a 409 Conflict error.
The following example shows how to create an approved sender. For more information about creating an approved sender, see CreateSender.
POST /20170907/senders
{
"compartmentId": "ocid1.compartment.oc1..aaaaaaaat7uqcb6zoxvzoga4d4vh4dtweciavepacd3skz56atf3qp73d7fx",
"emailAddress": "user@example.com",
}
Sender Policy Framework (SPF) is used by email receivers to detect email spoofing. Using SPF, an email receiver can check if the Internet Protocol (IP) is explicitly authorized to send for that domain. SPF is implemented by publishing a special TXT record to a domain's DNS records. The TXT record declares which hosts are allowed to send mail on behalf of this domain. Receiving mail servers check the SPF records of sending domains to verify that the email's source IP address is authorized to send from that domain. Without SPF, a spam or phishing email can be “spoofed” to appear that the email comes from a legitimate domain. Domains that implement SPF are much more likely to block emails attempting to spoof your domain. For an overview of how SPF works, see Sender Policy Framework. For details on SPF record syntax, see SPF Record Syntax.
The Approved Senders section within the Console provides validation of an SPF record for each of your approved senders.
- Open the navigation menu. Under Solutions and Platform, go to Email Delivery and click Email Approved Senders.
-
Select the checkbox for the approved sender you want to view SPF details for and click View SPF.
Tip
You can search for an approved sender by using the Search field. Addresses can be sorted alphanumerically or by creation date in ascending or descending order. -
The Manage SPF dialog box appears indicating whether an SPF record for the approved sender exists.
- If your domain does not currently have an SPF record, the information necessary to add an SPF record in your DNS setup is displayed. See Managing DNS Service Zones for instructions on adding a zone record in Oracle Cloud
Infrastructure. If your DNS setup resides with another provider, please reference their documentation for adding a TXT record to your domain.
In your DNS setup, create a TXT record and paste the following information into the record based on the sending location:
Sending Location SPF Record Americas v=spf1 include:rp.oracleemaildelivery.com ~all
Asia/Pacific v=spf1 include:ap.rp.oracleemaildelivery.com ~all
Europe v=spf1 include:eu.rp.oracleemaildelivery.com ~all
All Commercial Regions v=spf1 include:rp.oracleemaildelivery.com include:ap.rp.oracleemaildelivery.com include:eu.rp.oracleemaildelivery.com ~all
- If your domain does not currently have an SPF record, the information necessary to add an SPF record in your DNS setup is displayed. See Managing DNS Service Zones for instructions on adding a zone record in Oracle Cloud
Infrastructure. If your DNS setup resides with another provider, please reference their documentation for adding a TXT record to your domain.
Set up and test your SMTP connection using an SMTP library or product such, as Postfix or Sendmail, to send email through Oracle Cloud Infrastructure Email Delivery.
SMTP Connection Endpoints
Use the following regional endpoints for establishing SMTP connections for sending.
- YNY: smtp.email.ap-chuncheon-1.oci.oraclecloud.com
- HYD: smtp.email.ap-hyderabad-1.oci.oraclecloud.com
- MEL: smtp.email.ap-melbourne-1.oci.oraclecloud.com
- BOM: smtp.email.ap-mumbai-1.oci.oraclecloud.com
- KIX: smtp.email.ap-osaka-1.oci.oraclecloud.com
- ICN: smtp.email.ap-seoul-1.oci.oraclecloud.com
- SYD: smtp.email.ap-sydney-1.oci.oraclecloud.com
- NRT: smtp.email.ap-tokyo-1.oci.oraclecloud.com
- YUL: smtp.email.ca-montreal-1.oci.oraclecloud.com
- YYZ: smtp.email.ca-toronto-1.oci.oraclecloud.com
- AMS: smtp.email.eu-amsterdam-1.oci.oraclecloud.com
- FRA: smtp.email.eu-frankfurt-1.oci.oraclecloud.com
- ZRH: smtp.email.eu-zurich-1.oci.oraclecloud.com
- DXB: smtp.email.me-dubai-1.oci.oraclecloud.com
- JED: smtp.email.me-jeddah-1.oci.oraclecloud.com
- SCL: smtp.email.sa-santiago-1.oci.oraclecloud.com
- GRU: smtp.email.sa-saopaulo-1.oci.oraclecloud.com
- CWL: smtp.email.uk-cardiff-1.oci.oraclecloud.com
- LHR: smtp.email.uk-london-1.oci.oraclecloud.com
- IAD: smtp.email.us-ashburn-1.oci.oraclecloud.com
- PHX: smtp.email.us-phoenix-1.oci.oraclecloud.com
- SJC: smtp.email.us-sanjose-1.oci.oraclecloud.com
TLS Requirements
Oracle maintains strict security policies and only accepts email traffic using Transport Layer Security (TLS). Use of TLS 1.2 is mandatory to send email using Oracle Cloud Infrastructure.
The approved TLS 1.2 ciphers are:
- TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
- TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
- TLS_RSA_WITH_AES_256_CBC_SHA256
- TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
To access SMTP sending information to configure the connection in your system
Open the navigation menu. Under Solutions and Platform, go to Email Delivery and click Email Configuration. The following information is displayed:
- Public Endpoint: The public endpoint used to send email to for this region.
- SMTP Ports: The SMTP ports used to accept email. Email Delivery supports TLS on port 25 or 587.
-
Security: This field indicates if TLS, the standard means of performing encryption in transit for email, is being used. Customers must encrypt email while it is in transit to the Oracle Cloud Infrastructure Email Delivery service. Encrypted emails are protected from being read during transit.
Tip
Java applications (including JavaMail) must be updated to the latest version to ensure the latest protocols, ciphers, and security patches are in compliance with Oracle's supported security policies and ciphers.
Use Email Delivery to begin sending email.
Suppression List
As you begin to send email, Email Delivery automatically adds email addresses with bounce codes showing permanent failures or user complaints to the suppression list to protect your sender reputation. Email Delivery will not send any messages to these recipients in the future. Reasons for suppression currently include:
- Complaints
- Hard bounces
- Repetitive soft bounces
- Manual entries
- List-unsubscribe requests
- Open the navigation menu. Under Solutions and Platform, go to Email Delivery and click Email Suppression List.
- Click Add Suppression.
- In the Add Suppression dialog box, enter the email address.
- Click Add. The email address is added to the suppression list.
For more information, see Managing the Suppression List.
The following example shows how to add an email address to the suppression list. For more information about managing the suppressions list, see GetSuppression and DeleteSuppression.
POST /20170907/suppressions
{
"compartmentId": "ocid1.compartment.oc1..aaaaaaaat7uqcb6zoxvzoga4d4vh4dtweciavepacd3skz56atf3qp73d7fx",
"emailAddress": "user@example.com",
}
Using the API
You can access Oracle Cloud Infrastructure using the REST API. Instructions for the API are included in topics throughout this guide. For a list of available SDKs, see SDKs and Other Tools.
Regions
See Regions and Availability Domains for information on regions Email Delivery is available in.
Limits
See Email Delivery Service Capabilities and Limits for information on new account and enterprise account limits.
Best Practices
This section describes best practices for using Email Delivery.
Volume Testing - In order to maintain our sender reputation and yours, testing at volume needs to be done using the following best practice.
- Use a recipient address at the email-blackhole.com domain, such as example@email-blackhole.com. Email Delivery will accept the mail but will not deliver it to an inbox.
- If large volume emails are sent to valid email addresses, these will get rejected by receivers and will result in a large amount of hard bounces. This will negatively affect IP reputation. For testing bounce processing, send small amounts of emails to a domain that does not have an MX record, in other words, the domain does not exist.
Deliverability - To help you learn and manage the habits that affect your sending reputation, see Deliverability Best Practices.
Sending to Email Aliases - When sending email to an alias, the alias is considered one recipient. When sending email to a distribution group or list set up in an email client such as Apple Mail or Outlook, a separate email is sent for each recipient in the group.