Send Emails from your Custom App with OCI Email Delivery and OCI Functions

Send Emails from your Custom App with OCI Email Delivery and OCI Functions

We often need to send emails from our custom applications, either to inform users about something, or maybe for a password reset, etc. This sounds very simple and straightforward, but it can get complicated when you need to set up and manage an SMTP server and other additional services. It can also get expensive in some use-cases.

Let’s see how easy it is to send emails from a custom application running on OCI (or anywhere else as a matter of fact) using OCI Email Delivery, OCI Functions, and OCI API Gateway (optionally).

We’ll use only OCI Managed Services and an already developed OCI Function, so all you need to do is configure everything once following the guide below and then just use it without ever worrying about the infrastructure or anything else.

Overview of the Solution

To put it in a few words: Your App can send emails with a simple REST API Call. 

Here’s an overview of the solution:

Let’s break it step by step:

  1. Your application will make a REST API Call with the necessary content to send the email
  2. The call will be made either to an OCI API Gateway (this is optional, but it makes our life easier and it can manage the Auth Z/N for us plus other nice features) or directly to the OCI Function invoke endpoint
    1. In this example, we’ll use the OCI API Gateway
    2. If you don’t want to use OCI API Gateway, here is a great blog about different ways of invoking an OCI Function
  3. The OCI Function will then use the managed SMTP server – OCI Email Delivery – to send the email to the recipient
  4. Everything can be logged into one single place using OCI Logging to gain visibility over the whole workflow

Now that we have an overview, let’s start implementing it.

Step 1: Setup Email Delivery

Setup Email Domain & Approved Sender

  • In the OCI Console, navigate to Developer Services and then Email Delivery:

  • Navigate to Email Domains and click on Create Email Domain then add your domain name:

 

Generate SMTP Credentials

  • Navigate to Configuration and note down the Public Endpoint and SMTP Port

  • Create or use an existing user and give it the at least following permissions:
Allow group <senders group name> to use email-family in compartment <compartment name>
  • Navigate to this user profile using the top bar (if you’re logged in with it) or select it from the list of users and click on SMTP Credentials then click on Generate SMTP Credentials

  • Note down the SMTP Username & Password

At this point, you should have everything needed for the Email Delivery:

  • Approved sender
  • The SMTP Public Host
  • One of the provided SMTP Ports
  • SMTP Username & Password

Step 2: Setup Function to Send Emails

If you’re new to OCI Functions, please take a look at the Functions QuickStart on Cloud Shell.

We’re going to use one of the publicly available OCI Functions, oci-email-send-python, from the OCI Functions Samples GitHub Repository.

Deploy the oci-email-send-python Function

  • From the Developer Services click on Applications then on Create Application where you give it a name and you select an existing VCN and a Subnet for the Application (for simplicity, select a Public Subnet)

 

  • Follow the steps from the Cloud Shell Setup displayed in your new application for easy setup using the OCI Cloud Shell

git clone https://github.com/oracle/oracle-functions-samples.git
  • Navigate to the email delivery function
cd oracle-functions-samples/samples/oci-email-send-python
  • Deploy the function to your newly created Application
fn -v deploy --app <your-app-name>
  • Add the configuration variables needed for the function
fn config function <app-name> <function-name> smtp-username <SMTP-username>
fn config function <app-name> <function-name> smtp-password <SMTP-password>
fn config function <app-name> <function-name> smtp-host <SMTP-Server-name>
fn config function <app-name> <function-name> smtp-port <SMTP-Port>

Make sure you create the policies for OCI Functions. You can easily use the Functions use case from the Policy Builder. You just need to point it to your Group and Compartment:

Test the Function

We can easily test the function by invoking it from the Cloud Shell:

echo '{ "sender-email":"<approved-sender-email>", "sender-name":"<sender-name>", "recipient":"<recipient-email>", "subject":"<email-subject>", "body":"<email-body>" }' | fn invoke <app-name> oci-email-send-python

Here is an example:

echo '{ "sender-email":"function@example.com", "sender-name":"OCI Email Delivery", "recipient":" ionut@gmail.com", "subject":"Hello from OCI", "body":"This email was sent by an OCI Function using OCI Email Delivery" }' | fn invoke oci-send-email oci-email-send-python

Step 3: Setup API Gateway

  • Navigate to Developer Services click on Gateways under API Management and Create Gateway. Give it a name and put it in a Public Subnet (or Private, depending on your use case)

  • Configure your Route with a Path of your choice, and then select POST and your OCI Function

  • Create your Deployment
  • Make sure your API Gateway has the rights to call OCI Functions and you have port 443 opened in your VCN
ALLOW any-user to use functions-family in compartment <functions-compartment-name> where ALL {request.principal.type= 'ApiGateway', request.resource.compartment.id = '<api-gateway-compartment-OCID>'}

Test the API Gateway

We’re going to use Postman to test, but you can easily do this with cURL or any other way of calling REST endpoints.

Step 4: Enable Logging

Observability is very important and OCI provides a very easy way of enabling Logging for all the services we used.

  • Navigate to Observability & Management and clock on  Log Groups under Logging
  • It is recommended to create a separate log group for all resources used for sending emails, but you can use the Default_Group as well

  • Once your log group is created, navigate to the Logs menu and click on Enable service log

  • Now we can select each service used for sending emails from the Service list and then select the associated Resource to enable logging.
  • Here’s an example for Email Delivery

  • You can now do the same for all services: OCI Email Deliver, OCI Functions, OCI API Gateway and enable the Log Category you want. You can enable all if you want

  • Now when you go to Log Search, you can filter on this Log Group and you’ll see all logs from all services in one single view

You can also bring in your custom application logs by creating a custom log.

Step 5: Start Sending Emails from your App

Using an already developed OCI Function and OCI Managed Services, your App can easily send emails to your recipients. Your application just needs to call the Gateway endpoint and pass the body with the necessary info. Check this blog post about all the different ways of invoking an OCI Function if you don’t want to use the OCI API Gateway in front.

Of course, you can easily adapt and modify the OCI Function to make it better for your use case, but this is a great starting point.

This is a very cheap solution as well:

Ionut Adrian Vladu

I enjoy building python scripts for…everything! I am a Cloud enthusiast and I like to keep up with technology. When I'm not behind a computer, I like taking photos -- Visit My 500px profile -- or sit back and enjoy Formula 1 race weekends. Currently, working as a Tech Cloud Specialist @ Oracle
Subscribe
Notify of
guest
0 Comments
Inline Feedbacks
View all comments