SendGrid Node

The SendGrid Node allows a workflow to send emails using the configured SendGrid account.

Node Properties

The SendGrid Node takes several configuration properties for authenticating the request, defining the email content, and configuring the recipients …

Authentication

First, choose whether to authenticate the request from a SendGrid Service Credential (recommended) or to enter your SendGrid API key directly in the node. An API key always starts with the characters “SG.”.

An API key can be generated in the SendGrid account settings, and we recommend generating a new key specifically for use within this application.

Note: Pulling the API key from a service credential is not supported in Edge Workflows.

Message Contents

Next, configure the following fields defining the message contents …

• From Address Template: A string template for the “From” email address used to deliver the message. This address should be a verified sender in your SendGrid account.
• Reply-To Template: A string template for the email address where any replies will be sent. This field is optional, and if not provided, replies will be sent to the “From” email address.
• Email Subject Template: A string template for the subject line of the email.
• Email Body Template (HTML): A string template that should resolve to valid HTML, which serves as the message body.

In the example above, the “From” address is set to noreply@example.com; there is no “Reply To” address set; the subject is set to Temperature High for Device {{deviceName}}; and the body contains the text Temperature recorded as {{data.temp}}..

Recipient Addresses

Next, configure the recipients of the email as string templates. At least one “To”, “CC”, or “BCC” address must be provided; you may provide one or more addresses of each type.

For each recipient type, addresses may be provided through a combination of the following methods …

• One address per line.
• Multiple addresses per line, separated by commas (,) or semicolons (;).
• A string template referencing an address, a string of comma- or semicolon-separated addresses, or an array of addresses on the payload.

For example, given the following payload …

{
  "working": {
    "emails": [
        "success@weg.net, hello@weg.net, support@weg.net",
        "administrator@example.com"
    ],
    "extraAddress": "a-third-recipient@example.com"
  }
}

… and a SendGrid Node with “To” addresses defined as follows …

1. my-recipient@example.com; another-recipient@example.com
2. {{working.extraAddress}}
3. {{working.emails}}

… this would result in emails being sent to seven different addresses.

Attachments

Optionally, you may also add up to 10 attachments to send as part of the email. Each attachment takes the following properties …

• Input Type: Choose whether to provide the content inline (“File Content Template”) or from a URL (“File URL Template”). Depending on the chosen method, you must then provide either …

  • Content Template: A required string template that resolves to some content on your payload in any format (plain text, JSON, binary, etc.). The content will be Base64-encoded for conversion to an attachment, unless the content has already been Base64-encoded.
  • URL Template: A required string template that resolves to a publicly available URL from which the attachment can be retrieved. The content will be downloaded from that URL and provided as an attachment on the sent email.
• File Name Template: An optional string template resolving to a file name for the attachment, including the extension. If not provided, default file names will be added.

Note: For Edge Workflows, attachments can only be added in GEA version 1.43.3 and later.

Result

Optionally, specify a payload path where the result of the send request can be placed on the current payload. This can be used to verify the request was successful or to take another action in the event of an error.

{
  "time": Fri Feb 19 2016 17:26:00 GMT-0500 (EST),
  "data": {
    "power": 17
  },
  "applicationId": "568beedeb436ab01007be53d",
  "applicationName": "Embree",
  "triggerId": "56c74add04d0b50100043381-EkjUNjEol",
  "triggerType": "virtualButton",
  "flowId": "56c74add04d0b50100043381",
  "flowName": "Power Consumption Warning",
  "sendgridResult": {
    "message": "success"
  },
  "globals": {}
}

Node Example

If the SendGrid Node successfully sends a message, the following is placed on the payload (assuming a result path of working.sendGridResult) …

{
  "working": {
    "sendGridResult": {
      "message": "success"
    }
  }
}

Note: This does not necessarily mean that the email successfully reached all of its recipients - only that the request was successfully sent to SendGrid. The email could have been rejected by the recipient’s server or caught by a spam filter. Users should check their SendGrid account logs if messages are not being received as expected.

Node Errors

The SendGrid Node can fail for multiple reasons, and in each case, this will result in an error property being placed on the payload at the provided result path. For example, given a path of working.sendGridResult, the payload would look like the following in the event of an invalid API key …

{
  "working": {
    "sendGridResult": {
      "error": {
        "errors": [
          {
            "field": null,
            "help": null,
            "message": "The provided authorization grant is invalid, expired, or revoked"
          }
        ]
      }
    }
  }
}

Another possible error is invalid email addresses being provided for the recipients; in such a case, the SendGrid Node’s result may look like the following …

{
  "working": {
    "sendGridResult": {
      "error": "Provide at least one of to, cc or bcc"
    }
  }
}

Related Nodes

• Email Node
• Mailgun Node
• Inbound Email Trigger