Oracle Cloud Infrastructure Documentation

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

This diagram shows the architectural flow of the Email Delivery service.

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 takes 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.

Using the Email Delivery SDK

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:

Deliverability Best Practices

Email Deliverability is commonly known as the ability to deliver bulk and transactional emails to opt-in recipient inboxes. Refer to Email Deliverability for information on best practices, troubleshooting undelieverd emails, and other options to improve inbox placement. For more best practice guidelines, see Best Practices.

Sending Email

To begin sending email with Email Delivery, complete the following steps:

Generate SMTP credentials for a user.

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.

To generate SMTP credentials for a user
  1. View the user's details:
    • If you're generating SMTP credentials for yourself:

      Open the Profile menu (User menu icon) and click User Settings.

    • If you're an administrator generating SMTP credentials for another user: Open the navigation menu and click Identity & Security. Under Identity, click Users. Locate the user in the list, and then click the user's name to view the details.
  2. Click SMTP Credentials.

  3. Click Generate SMTP Credentials.

  4. Enter a Description of the SMTP Credentials in the dialog box.
  5. Click Generate SMTP Credentials. A user name and password is displayed.

  6. Copy the user name and password for your records and click Close. Copy the credentials immediately, because you can't retrieve the password again after closing the dialog box for security reasons.

    If you're an administrator creating the credential set for another user, you need to securely deliver it to the user by providing it verbally, printing it out, or sending it through a secure email service.

Set up permissions.

The new user must be assigned to a group with permissions to manage the email-family resources.

To create a policy to allow a group to manage email-family resources
  1. Open the navigation menu and click Identity & Security. Under Identity, click Policies. A list of the policies in the compartment you're viewing is displayed.
  2. If you want to attach the policy to a compartment other than the one you're viewing, select the compartment from the list on the left. Where the policy is attached controls who can later modify or delete it (see Overview of Policies).
  3. Click Create Policy.
  4. 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 email-family 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 whether to apply tags, skip this option (you can apply tags later) or ask your administrator.
  5. Click Create.
The new policy goes into effect typically within 10 seconds.

See Managing Approved Senders and Generate SMTP Credentials for a User for more details on Email sending related policy setup requirements.

Suppressions policy must be set at the tenancy level. For more information, see Managing the Suppression List.

To add the new user to the group
  1. Open the navigation menu and click Identity & Security. Under Identity, click Users. A list of the users in your tenancy is displayed.
  2. Locate the user in the list.
  3. Click the user. Its details are displayed.
  4. Click Groups.
  5. Click Add User to Group.
  6. 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.

Set up an email domain with DKIM.
Here's the general process for setting up a sending domain with DKIM:
  1. Create the email domain: An email domain lets you set up important authentication measures for sending email, essential to ensure good email delivery reputation.
  2. Configure DKIM: Configure DKIM for this email domain. This is an important step to help ensure email is delivered and reaches the inbox. Create at least one DKIM.
  3. Add the DKIM record to your DNS setup: The system generated CNAME record and value can be used in the DNS setup for your email domain. You must add the record to your DNS setup and allow it to propagate throughout the internet before you can activate the DKIM record.
  4. Activate the DKIM record: Activate the DKIM record to enable signing and authentication of your emails.

    For more information, see Managing DKIM.

Create an approved sender.

An approved sender must be set up for all “From:” addresses sending mail through Oracle Cloud Infrastructure, or mail is 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 US West (Phoenix) region, you cannot send email through the US East (Ashburn) region with that sender.

Best Practices: 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.

Use of multiple addresses in the email From header is discouraged. If you use multiple addresses, it increases the possibility that your mail is placed in a spam folder or discarded (because of DMARC From alignment rules). The performance of your emails is reduced because all addresses have to be authorized as approved senders. A best practice for the SMTP envelope From address is to match the header From address when you submit mail to Email Delivery. If you use mismatched addresses, it reduces the performance of your emails because both addresses need to be authorized as approved senders. Certain future platform features will not be available if you use mismatched addresses.

To create an approved sender using the Console
  1. Open the navigation menu and click Developer Services. Under Application Integration, click Email Delivery. In the Resources menu, click 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.
  2. Click Create Approved Sender within the Approved Senders view.
  3. Enter the email address you want to list as an approved sender in the Add Sender dialog box.
  4. Click Add. The email address is added to your Approved Senders list.
Tip

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.
To create an approved sender using the API

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",
				
		}
Configure SPF on the approved sender domain.

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.

To configure SPF
  1. Open the navigation menu and click Developer Services. Under Application Integration, click Email Delivery. In the Resources menu, click Approved senders.

  2. 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.

  3. 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
Configure the SMTP connection.

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.

Sending Region SMTP Endpoint
South Africa Central (Johannesburg) smtp.email.af-johannesburg-1.oci.oraclecloud.com
South Korea North (Chuncheon) smtp.email.ap-chuncheon-1.oci.oraclecloud.com
India South (Hyderabad) smtp.email.ap-hyderabad-1.oci.oraclecloud.com
Australia Southeast (Melbourne) smtp.email.ap-melbourne-1.oci.oraclecloud.com
India West (Mumbai) smtp.email.ap-mumbai-1.oci.oraclecloud.com
Japan Central (Osaka) smtp.email.ap-osaka-1.oci.oraclecloud.com
South Korea Central (Seoul) smtp.email.ap-seoul-1.oci.oraclecloud.com
Australia East (Sydney) smtp.email.ap-sydney-1.oci.oraclecloud.com
Singapore (Singapore) smtp.email.ap-singapore-1.oci.oraclecloud.com
Japan East (Tokyo) smtp.email.ap-tokyo-1.oci.oraclecloud.com
Canada Southeast (Montreal) smtp.email.ca-montreal-1.oci.oraclecloud.com
Canada Southeast (Toronto) smtp.email.ca-toronto-1.oci.oraclecloud.com
Netherlands Northwest (Amsterdam) smtp.email.eu-amsterdam-1.oci.oraclecloud.com
Germany Central (Frankfurt) smtp.email.eu-frankfurt-1.oci.oraclecloud.com
France South (Marseille) smtp.email.eu-marseille-1.oci.oraclecloud.com
Italy Northwest (Milan) smtp.email.eu-milan-1.oci.oraclecloud.com
Sweden Central (Stockholm) smtp.email.eu-stockholm-1.oci.oraclecloud.com
Switzerland North (Zurich) smtp.email.eu-zurich-1.oci.oraclecloud.com
Israel Central (Jerusalem) smtp.email.il-jerusalem-1.oci.oraclecloud.com
UAE Central (Abu Dhabi) smtp.email.me-abudhabi-1.oci.oraclecloud.com
UAE East (Dubai) smtp.email.me-dubai-1.oci.oraclecloud.com
Saudi Arabia West (Jeddah) smtp.email.me-jeddah-1.oci.oraclecloud.com
Chile (Santiago) smtp.email.sa-santiago-1.oci.oraclecloud.com
Brazil East (Sao Paulo) smtp.email.sa-saopaulo-1.oci.oraclecloud.com
Brazil Southeast (Vinhedo) smtp.email.sa-vinhedo-1.oci.oraclecloud.com
UK West (Newport) smtp.email.uk-cardiff-1.oci.oraclecloud.com
UK South (London) smtp.email.uk-london-1.oci.oraclecloud.com
US East (Ashburn) smtp.email.us-ashburn-1.oci.oraclecloud.com
US West (Phoenix) smtp.email.us-phoenix-1.oci.oraclecloud.com
US West (San Jose) 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 and click Developer Services. Under Application Integration, click Email Delivery. In the Resources menu, click 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 that the latest protocols, ciphers, and security patches are in compliance with Oracle's supported security policies and ciphers.
Begin sending email.

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
To manually add an email address to the suppression list using the Console
  1. Open the navigation menu and click Developer Services. Under Application Integration, click Email Delivery. In the Resources menu, click Suppression list.
  2. Click Add Suppression.
  3. In the Add Suppression dialog box, enter the email address.
  4. Click Add. The email address is added to the suppression list.

For more information, see Managing the Suppression List.

To manually add an email address to the suppression list using the API

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.

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 Email Deliverability.

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.