SendGrid

The SendGrid task is used to send emails through the SendGrid platform. Use this task in workflows when you need to programmatically deliver emails such as alerts, confirmations, or updates.

The task uses a pre-configured SendGrid integration for authentication and delivery. Upon execution, it connects to the SendGrid API and sends the email as defined in the task configuration, which includes the sender and recipient email addresses, email subject, and message body.

Prerequisites

• Integrate SendGrid with Orkes Conductor.

Task parameters

Configure these parameters for the SendGrid task.

Parameter	Description	Required/ Optional
inputParameters.from	The sender’s email address. This must be a verified email in SendGrid. Learn more.	Required.
inputParameters.to	The recipient’s email address.	Required.
inputParameters.subject	The email subject.	Required.
inputParameters.contentType	The type of email content. Supported values: text/plain text/html	Required.
inputParameters.content	The email body.	Required.
inputParameters.sendgridConfiguration	The name of the SendGrid integration that is configured in your cluster.	Required.

Caching parameters

You can cache the task outputs using the following parameters. Refer to Caching Task Outputs for a full guide.

Parameter	Description	Required/ Optional
cacheConfig.ttlInSecond	The time to live in seconds, which is the duration for the output to be cached.	Required if using cacheConfig.
cacheConfig.key	The cache key is a unique identifier for the cached output and must be constructed exclusively from the task’s input parameters. It can be a string concatenation that contains the task’s input keys, such as ${uri}-${method} or re_${uri}_${method}.	Required if using cacheConfig.

Schema parameters

You can enforce input/output validation for the task using the following parameters. Refer to Schema Validation for a full guide.

Parameter	Description	Required/ Optional
taskDefinition.enforceSchema	Whether to enforce schema validation for task inputs/outputs. Set to true to enable validation.	Optional.
taskDefinition.inputSchema	The name and type of the input schema to be associated with the task.	Required if enforceSchema is set to true.
taskDefinition.outputSchema	The name and type of the output schema to be associated with the task.	Required if enforceSchema is set to true.

Other generic parameters

Here are other parameters for configuring the task behavior.

Parameter	Description	Required/ Optional
optional	Whether the task is optional. The default is false. If set to true, the workflow continues to the next task even if this task is in progress or fails.	Optional.

Task configuration

This is the task configuration for a SendGrid task.

   {
     "name": "sendgrid",
     "taskReferenceName": "sendgrid_ref",
     "inputParameters": {
       "from": "john.doe@acme.com",
       "to": "jane.doe@acme.com",
       "subject": "Email Subject",
       "contentType": "text/plain",
       "content": "Email Body",
       "sendgridConfiguration": "<INTEGRATION-NAME>"
     },
     "type": "SENDGRID"
   }

Task output

The SendGrid task will return the following parameters.

Parameter	Description
response	A JSON object representing the response, if present.
headers	An object containing the metadata about the response.
statusCode	The HTTP status code indicating success or failure of the request.
body	The response body containing the data returned by the API.

Adding a SendGrid task in UI

To add a SendGrid task:

1. In your workflow, select the (+) icon and add a SendGrid task.
2. In From, enter the verified SendGrid sender email.
3. In To, enter the recipient’s email address.
4. In Content Type, select the type of email content as text/plain or text/html.
5. In Content, enter the email body.
6. In SendGrid Configuration, select the SendGrid integration added to the cluster.

Examples

Here are some examples for using the SendGrid task.

Using the SendGrid task in a workflow

Notification workflows are common when end users must be alerted, such as for payments, alerts, or failures.

Consider a scenario where an organization uses SendGrid as its email notification platform. To create a simple email notification flow using Orkes Conductor, first create a SendGrid integration in your Conductor cluster.

Once the integration is created, note its name. For example, let’s use “SendGrid”.

The following workflow uses this integration to send an email notification. To create the workflow in the Conductor UI:

1. Go to Definitions > Workflow from the left navigation menu on your Conductor cluster.
2. Select + Define workflow.
3. In the Code tab, paste the following code, replacing your SendGrid integration name and sender email:

{
 "name": "email-notification-workflow",
 "description": "Email notification workflow using SendGrid",
 "version": 1,
 "tasks": [
   {
     "name": "sendgrid",
     "taskReferenceName": "sendgrid_ref",
     "inputParameters": {
       "from": "john.doe@acme.com", //Verified sender email in SendGrid
       "to": "${workflow.input.recipientEmail}",
       "subject": "Your renewal failed",
       "contentType": "text/plain",
       "content": "Hello, This is to notify that your subscription renewal for XYZ failed. ",
       "sendgridConfiguration": "SendGrid" // Integration name in Orkes Conductor
     },
     "type": "SENDGRID"
   }
 ],
 "inputParameters": [
   "recipientEmail"
 ],
 "schemaVersion": 2
}

After saving the workflow, go to the Run tab, enter the recipient email address in the input parameter field, and select Execute to run the workflow.

This starts the workflow and opens the workflow execution page, where you can monitor its progress. After the workflow is complete, the status changes to Completed.

Verify email delivery from the recipient’s inbox.