Skip to content

How to send email

This how-to guide covers how to send email from an application which requires SMTP and cannot be modified to use the User Notify client library.

Prerequisites

This section describes what you must have before following this how-to.

Service registration

You must have first registered your service. You should have a "service id" as part of that step. In this guide we shall use punt-booker as an example service id.

Service account

You must have first created one or more Google Service accounts which will be able to send email. These service accounts must be registered with the User Notify service and associated with tour service id.

Hosting

Your application must be being run a) in a containerised environment and b) with ambient Google API credentials for the email sending service account or which can impersonate it. For example, the following deployments match these requirements:

  • Your application runs as a container via Google Cloud Run and is configured to run with the identity of a specific Google Service Account.
  • Your application runs in a pod within a Google Kubernetes Engine (GKE) cluster.
  • Your application runs in an on-premises VM and a service account's JSON credentials are available at a location pointed to by the GOOGLE_APPLICATION_CREDENTIALS environment variable.
  • Your application runs in a VM hosted in Google Cloud.

You must determine how to launch a "sidecar" container for your application. For example, in Google Cloud, this is done by adding an additional container in the terraform resource.

Tip

Make sure you know if your application's ambient credentials are for the email sending Service Account or will be used to impersonate the email sending Service Account. If you are using impersonation then you will need to grat your application's Service Account the roles/serviceAccountTokenCreator role on the email sending Service Account.

Sending email

Deploy the latest release of the registry.gitlab.developers.cam.ac.uk/uis/devops/user-notify/ucam-user-notify/smtp-bridge image as a sidecar container. Your hosting platform must arrange for sidecar containers to be accessible to the main application container on localhost. Both Cloud Run and Google Kubernetes Engine support this.

Important

There is no latest tag for that image. You MUST deploy a specific version.

Set the following environment variables on the sidecar container:

  • USER_NOTIFY_SERVICE_NAME (required) - the id of your service as registered with User Notify.
  • USER_NOTIFY_IMPERSONATE_SERVICE_ACCOUNT (optional) - if your application needs to impersonate the email sending Service Account, set this environment variable to the email-formatted identifier for the Service Account.
  • USER_NOTIFY_SMTP_PORT (optional, greater than 1023) - port which the SMTP container will listen on. The default is 1025.

Configure your application to use SMTP with the following configuration:

  • Host: localhost
  • Port: 1025 (or, if you've customised the port number above, the custom port number)
  • Authentication: none
  • TLS/STARTTLS: none

Next steps