Note:

• This tutorial requires access to Oracle Cloud. To sign up for a free account, see Get started with Oracle Cloud Infrastructure Free Tier.
• It uses example values for Oracle Cloud Infrastructure credentials, tenancy, and compartments. When completing your lab, substitute these values with ones specific to your cloud environment.

Send Emails using the Oracle Cloud Infrastructure Email Delivery Service HTTP Interface

Introduction

Oracle Cloud Infrastructure (OCI) Email Delivery is an email sending service that provides a fast and reliable managed solution for sending both high volume bulk and transactional emails. Previously, OCI Email Delivery contained only a Simple Mail Transfer Protocol (SMTP) interface. However, we recently announced a new HTTPS REST API for email submission, improving performance, eliminating configuration complexity, and increasing rates of successful inbox placement.

Objective

• Send emails using the OCI Email Delivery Service HTTP interface.

Prerequisites

• A user with sufficient permissions to send email using OCI Email Delivery. For more information, see the policies here.

• An OCI Email Delivery domain. For more information to set up an OCI Email Delivery domain, see Step-by-step instructions to send email with OCI Email Delivery.

Task 1: Understand the Authentication Methods

HTTPS email submissions support standard OCI SDK authentication methods. In this tutorial, we will demonstrate API key-based authentication and instance principal authentication. For more information, see OCI SDK Authentication Methods.

• API Key-Based Authentication

  In this authentication, you will create a configuration file and store it on the local machine. Therefore, it should be used only from a secure network and when you are comfortable storing private keys locally. The file contains the following details.

  • User Oracle Cloud Identifier (OCID)
  • Tenancy OCID
  • Region
  • Private key path
  • Fingerprint

  For more information about how to create and gather the above parameters, see Required Keys and OCIDs.

• Instance Principal Authentication

  Instance principal authentication involves authorizing an instance to make API calls on OCI services by way of a dynamic group. Create a dynamic group, matching rules, and proper policies. For more information, see Managing Dynamic Groups.

  To enable the instance to send emails, use the following policy.

  Allow dynamic-group <dynamic-group-name> to use email-family in compartment <compartment-name>
  

  For more information about how to customize these permissions further, see Details for the Email Delivery Service.

Task 2: Send Email

We will be using the Python software development kit (SDK), but any SDK or the Oracle Cloud Infrastructure Command Line Interface (OCI CLI) can be substituted. For more information about how to install, see Software Development Kits and Command Line Interface.

Note: Refer to the Email Delivery API for a full list of available parameters.

• API Key-Based Authentication

  	import oci
  
  	#Create a default config
  	config = oci.config.from_file()
  
  	#Initialize service client with config file
  	email_client = oci.email_data_plane.EmailDPClient(config)
  
  	#Create the email details
  	email_details = oci.email_data_plane.models.SubmitEmailDetails(
  			sender = oci.email_data_plane.models.Sender(
  					sender_address = oci.email_data_plane.models.EmailAddress(
  							email = '<approved sender email>',
  							name = '<sender name>'),
  					compartment_id = '<compartment ocid>'),
  			recipients = oci.email_data_plane.models.Recipients(
  					to = [
  							oci.email_data_plane.models.EmailAddress(
  									email = '<to email address>',
  									name = '<to name>'
  							)],
  					cc = [
  							oci.email_data_plane.models.EmailAddress(
  									email = '<cc email address>',
  									name '<cc name>'
  							)],
  					bcc = [
  							oci.email_data_plane.models.EmailAddress(
  									email = '<bcc email address>',
  									name '<bcc name>'
  									)]),
  			subject = '<email subject>',
  			body_text = '<email body>',
  	)
  
  	#Submit the email
  	email_client.submit_email(email_details)
  

  Download the Python SDK client configuration example from here: configuration_example.py.

• Instance Principal Authentication

  	import oci
  
  	compartment_id = '<compartment ocid>'
  
  	# By default this will hit the auth service in the region returned by http://169.254.169.254/opc/v2/instance/region on the instance.
  	signer = oci.auth.signers.InstancePrincipalsSecurityTokenSigner()
  
  	# In the base case, configuration does not need to be provided as the region and tenancy are obtained from the InstancePrincipalsSecurityTokenSigner
  	identity_client = oci.identity.IdentityClient(config={}, signer=signer)
  
  	#Create the email details
  	email_details = oci.email_data_plane.models.SubmitEmailDetails(
  			sender = oci.email_data_plane.models.Sender(
  					sender_address = oci.email_data_plane.models.EmailAddress(
  							email = '<approved sender email>',
  							name = '<sender name>'),
  					compartment_id = '<compartment ocid>'),
  			recipients = oci.email_data_plane.models.Recipients(
  					to = [
  							oci.email_data_plane.models.EmailAddress(
  									email = '<to email address>',
  									name = '<to name>'
  							)],
  					cc = [
  							oci.email_data_plane.models.EmailAddress(
  									email = '<cc email address>',
  									name '<cc name>'
  							)],
  					bcc = [
  							oci.email_data_plane.models.EmailAddress(
  									email = '<bcc email address>',
  									name '<bcc name>'
  									)]),
  			subject = '<email subject>',
  			body_text = '<email body>',
  	)
  
  	#Submit the email
  	email_client.submit_email(email_details)
  

  Download the Python SDK instance principal example from here: instance_principals_examples.py.

Task 3: Test at Volume

To maintain both your sender reputation and ours, use the following best practices in testing at volume.

• Use a receipt address at the discard.oracle.com domain, such as [e-mail]. OCI Email Delivery accepts the mail but does not deliver it to an inbox.

• If large volume emails are sent to valid email addresses, receivers reject them, resulting in many hard bounces. This result negatively affects IP reputation. For testing bounce processing, send small amounts of emails to a domain that does not exist.

Related Links

• Creating User Permissions

• Step-by-step instructions to send email with OCI Email Delivery

• OCI SDK Authentication Methods

• Required Keys and OCIDs

• Managing Dynamic Groups

• Software Development Kits and Command Line Interface

• Python SDK API key example: configuration_example.py

• Python SDK instance principal example: instance_principals_examples.py

Acknowledgments

• Author - Cody Brinkman (Cloud Architect)

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.

---

Title and Copyright Information

Send Emails using the Oracle Cloud Infrastructure Email Delivery Service HTTP Interface

F96609-02

May 2024

Copyright ©2024,

Oracle and/or its affiliates.