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

Using the Email Delivery SDK

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. 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 (User menu icon) and click User Settings.

  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.
Set up permissions.

The new user must be assigned to a group with permissions to manage approved-senders and suppressions.

To create a policy to allow a group to manage approved senders and suppressions
  1. 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.
  2. 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).
  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 approved-senders in compartment <compartment name>

      For more information about policies and policy syntax, see Policy Basics.

    • Tags: Optionally, you can apply tags. If you have permissions to create a resource, 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, skip this option (you can apply tags later) or ask your administrator.
  5. Click Create.

The new policy will go into effect typically within 10 seconds.

To add the new user to the group
  1. Open the navigation menu. Under Governance and Administration, go to Identity and 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.

Create an approved sender.

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.

To create an approved sender using the Console
  1. 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.
  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. Under Solutions and Platform, go to Email Delivery and click Email 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.

  • SJC: smtp.email.us-sanjose-1.oci.oraclecloud.com
  • 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
  • JED: smtp.email.me-jeddah-1.oci.oraclecloud.com
  • GRU: smtp.email.sa-saopaulo-1.oci.oraclecloud.com
  • LHR: smtp.email.uk-london-1.oci.oraclecloud.com
  • IAD: smtp.us-ashburn-1.oraclecloud.com
  • PHX: smtp.us-phoenix-1.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:

  • Manage SMTP Credentials: Access your user credentials. Use the SMTP user credentials (in plain text) when validating your connection.
  • Server Name: Regional SMTP endpoint
  • Port: Email Delivery supports TLS on port 25 or 587.
  • Use Transport Layer Security (TLS): 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.
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. Under Solutions and Platform, go to Email Delivery and click Email 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 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.