Action Provider: Send Notification Email

URL: https://actions.globus.org/notification/notify [Introspect]

Scope: https://auth.globus.org/scopes/5fac2e64-c734-4e6b-90ea-ff12ddbf9653/notification_notify

Synchronous / Asynchronous: Synchronous

The Send Notification Email action provider sends emails to one or more email addresses.

The request to send the email contains the standard components of an email: sender, receiver(s), subject and body. The mimetype of the body may be specified so that either HTML or text formatted messages may be sent. The body also supports the notion of variable substitution or "templating". Values in the body may be specified with a dollar sign prefix ($), and when values are provided in the body_variables property of the request, the template value will be substituted with the corresponding value from the body_variables.

The other important component of the request to this action provider is the email sending credentials. Credentials are provided to allow the provider to communicate with the service used for sending the email. Presently, two modes of sending email are supported: SMTP and AWS SES.

When SMTP is provided, the username, password and server hostname are required. (The port is optional, but recommended.)
When AWS SES is provided, the AWS access key, AWS access key secret and the AWS region must be provided.

The action provider will return success as long as the email service accepts the message. It cannot guarantee successful delivery of the message including an inability to deliver the message due to an improper recipient address.

Note

When sending an email via the action provider’s AWS SES mode, the IAM user associated with the access key must have the ses:SendRawEmail permission.

Usage Example

The example below demonstrates how to use the action provider in a flow.

Features of the flow:

__Private_Parameters is used to prevent the SMTP credentials from appearing in logs or error messages.
The body_template and body_variables demonstrate how to use an HTML template with the Notification Email action provider. Embedded quotation marks in the template are escaped with backslashes (\"). The template variable, report_id, is delimited by curly braces (${report_id}), which may not always be necessary but is a best practice.
The email subject is an expression (indicated by the .= suffix in the key name) and demonstrates how to create an email subject dynamically.
The $._context.email variable is used to identify the flow runner’s email address.

{
  "StartAt": "SMTPEmail",
  "States": {
    "SMTPEmail": {
      "Type": "Action",
      "ActionUrl": "https://actions.globus.org/notification/notify",
      "Parameters": {
        "body_mimetype": "text/html",
        "body_template": "<html><body><a href=\"https://domain.example/reports/${report_id}\">Your report is generated</a></body></html>",
        "body_variables": {
          "report_id.$": "$.report_id"
        },
        "destination.$": "$._context.email",
        "sender": "reports@domain.example",
        "subject.=": "'Report ' + report_id + ' available for review'",
        "__Private_Parameters": [
          "send_credentials"
        ],
        "send_credentials": [
          {
            "credential_type": "smtp",
            "credential_value": {
              "hostname": "smtp.domain.example",
              "username": "email@domain.example",
              "password": "password_or_api_key",
              "port": 587
            }
          }
        ]
      },
      "End": true
    }
  }
}

Features of the flow:

__Private_Parameters is used to prevent the SES credentials from appearing in logs or error messages.
The body_template and body_variables demonstrate how to use an HTML template with the Notification Email action provider. Embedded quotation marks in the template are escaped with backslashes (\"). The template variable, report_id, is delimited by curly braces (${report_id}), which is not always be necessary but is a best practice.
The email subject is an expression (indicated by the .= suffix in the key name) and demonstrates how to create an email subject dynamically.
The $._context.email variable is used to identify the flow runner’s email address.

{
  "StartAt": "SESEmail",
  "States": {
    "SESEmail": {
      "Type": "Action",
      "ActionUrl": "https://actions.globus.org/notification/notify",
      "Parameters": {
        "body_mimetype": "text/html",
        "body_template": "<html><body><a href=\"https://domain.example/reports/${report_id}\">Your report is generated</a></body></html>",
        "body_variables": {
          "report_id.$": "$.report_id"
        },
        "destination.$": "$._context.email",
        "sender": "reports@domain.example",
        "subject.=": "'Report ' + report_id + ' available for review'",
        "__Private_Parameters": [
          "send_credentials"
        ],
        "send_credentials": [
          {
            "credential_type": "ses",
            "credential_value": {
              "aws_access_key_id": "AID111111111111",
              "aws_secret_access_key": "1111111111111111111111111111",
              "region_name": "us-east-1"
            }
          }
        ]
      },
      "End": true
    }
  }
}

{
  "properties": {
    "report_id": {
      "title": "Report ID",
      "type": "string"
    }
  },
  "required": [
    "report_id"
  ],
  "additionalProperties": false
}

{
  "report_id": "12345-abc"
}