Skip to main content

SendGrid Component

Send emails through SendGrid

Component key: sendgrid

Changelog ↓

Description​

SendGrid is an email delivery service. This component allows you to send of emails through the SendGrid platform.

Connections​

SendGrid API Key​

Information about getting started and creating API keys with SendGrid can be found on their developer documentation site.

InputNotesExample
API Key

Provide the API Key obtained from the developer console.

Triggers​

Webhook​

Receive and validate webhook requests from SendGrid for webhooks you configure. | key: webhook

You can configure a SendGrid event webhook to send information to a flow's webhook URL when an email is received.

Data Sources​

SendGrid Contact Lists​

Fetch a picklist of contact lists from SendGrid | key: sendGridListsDataSource | type: picklist

InputNotesExample
Connection

{
  "result": [
    {
      "label": "Summer Newsletter (1020 contacts)",
      "key": "abc-123"
    },
    {
      "label": "Product Updates (50 contacts)",
      "key": "def-456"
    }
  ]
}

Actions​

Add or Update Contact​

Add or update a contact. This can also be used to add contacts to a list. | key: addOrUpdateContact

InputNotesExample
Contacts

An array of contact objects to add or update. See SendGrid docs for contact object structure.

List IDs

Comma-separated IDs of the lists to add the contact to. These lists must already exist.

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy
Connection

{
  "data": {
    "job_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "_metadata": {
      "self": "https://api.sendgrid.com/v3/marketing/contacts/imports/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  }
}

Create List​

Create a new contact list | key: createList

InputNotesExample
List Name

The name of the list to create.

My New Contact List
Connection

{
  "data": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "My New Contact List",
    "contact_count": 0,
    "_metadata": {
      "self": "https://api.sendgrid.com/v3/marketing/lists/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  }
}

Get All Field Definitions​

Retrieve all custom field definitions with pagination support | key: getAllFieldDefinitions

InputNotesExample
Page Size

Number of results to return per page (max 100).

10
Page Token

Token for fetching the next or previous page of results.

Connection

{
  "data": {
    "custom_fields": [
      {
        "id": "w1",
        "name": "pet",
        "field_type": "Text",
        "_metadata": {
          "self": "https://api.sendgrid.com/v3/marketing/field_definitions/w1"
        }
      }
    ],
    "reserved_fields": [
      {
        "id": "_rf1",
        "name": "first_name",
        "field_type": "Text",
        "_metadata": {
          "self": "https://api.sendgrid.com/v3/marketing/field_definitions/_rf1"
        }
      }
    ],
    "_metadata": {
      "count": 2,
      "self": "https://api.sendgrid.com/v3/marketing/field_definitions"
    },
    "pagination": {
      "nextPageToken": "next_page_token",
      "previousPageToken": "previous_page_token",
      "totalCount": 100
    }
  }
}

Get All Lists​

Retrieve all contact lists with pagination support | key: getAllLists

InputNotesExample
Page Size

Number of results to return per page (max 100).

10
Page Token

Token for fetching the next or previous page of results.

Connection

{
  "data": {
    "result": [
      {
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "name": "My Contact List",
        "contact_count": 1000,
        "_metadata": {
          "self": "https://api.sendgrid.com/v3/marketing/lists/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
        }
      }
    ],
    "_metadata": {
      "count": 1,
      "self": "https://api.sendgrid.com/v3/marketing/lists"
    },
    "pagination": {
      "nextPageToken": "next_page_token",
      "previousPageToken": "previous_page_token",
      "totalCount": 100
    }
  }
}

Get Contacts by Emails​

Retrieve contacts by their email addresses. | key: getContactsByEmails

InputNotesExample
Emails

Comma-separated email addresses to search for.

test1@example.com,test2@example.com
Connection

{
  "data": {
    "result": {
      "test1@example.com": {
        "contact": {
          "address_line_1": "123 Main St",
          "address_line_2": " Apt 4B",
          "alternate_emails": [
            "testalt@example.com"
          ],
          "city": "Anytown",
          "country": "US",
          "email": "test1@example.com",
          "first_name": "Test",
          "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "last_name": "User",
          "list_ids": [
            "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
          ],
          "postal_code": "12345",
          "state_province_region": "CA",
          "phone_number": "555-123-4567",
          "whatsapp": "15551234567",
          "line": "testuserline",
          "facebook": "testuserfb",
          "unique_name": "testuserunique",
          "custom_fields": {
            "field1": "value1"
          },
          "created_at": "2023-01-01T12:00:00Z",
          "updated_at": "2023-01-01T12:00:00Z",
          "_metadata": {
            "self": "url"
          }
        }
      }
    }
  }
}

Get Import Status​

Check the status of a contact import job | key: getImportStatus

InputNotesExample
Job ID

The job ID returned from Import Contacts, Add/Update Contact, or Delete Contacts operations.

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Connection

{
  "data": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "completed",
    "job_type": "upsert",
    "results": {
      "requested_count": 100,
      "created_count": 80,
      "updated_count": 20,
      "deleted_count": 0,
      "errored_count": 0,
      "errors_url": "https://api.sendgrid.com/v3/marketing/contacts/imports/errors/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "started_at": "2024-01-01T00:00:00Z",
      "finished_at": "2024-01-01T00:01:00Z"
    }
  }
}

Get List by ID​

Retrieve a specific contact list by its ID | key: getListById

InputNotesExample
Include Sample Contacts

Whether to include a sample of contacts in the response.

false
List ID

The ID of the list to retrieve.

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Connection

{
  "data": {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "My Contact List",
    "contact_count": 42,
    "contact_sample": [
      {
        "id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
        "email": "example@email.com",
        "first_name": "John",
        "last_name": "Doe",
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ],
    "_metadata": {
      "self": "https://api.sendgrid.com/v3/marketing/lists/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  }
}

Initiate Contacts Import​

Initiates a CSV contact import. Returns a URL and headers for uploading the CSV file. | key: initiateContactsImport

InputNotesExample
Field Mappings

An array of field definition IDs to map the uploaded CSV columns. Use null to skip a column. Get IDs from 'Get All Field Definitions' action.

Is Compressed

Set to true if the CSV file will be gzip-compressed.

false
List IDs

Comma-separated IDs of the lists to add the contact to. These lists must already exist.

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy
Connection

{
  "data": {
    "job_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "upload_uri": "https://s3.amazonaws.com/path/to/your/upload_location",
    "upload_headers": [
      {
        "header": "Content-Type",
        "value": "text/csv"
      },
      {
        "header": "x-amz-meta-job_id",
        "value": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    ],
    "_metadata": {
      "self": "https://api.sendgrid.com/v3/marketing/contacts/imports/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  }
}

Raw Request​

Send raw HTTP request to SendGrid | key: rawRequest

InputNotesExample
Connection
Data

The HTTP body payload to send to the URL.

{"exampleKey": "Example Data"}
Debug Request

Enabling this flag will log out the current request.

false
File Data

File Data to be sent as a multipart form upload.

[{key: "example.txt", value: "My File Contents"}]
File Data File Names

File names to apply to the file data inputs. Keys must match the file data keys above.

Form Data

The Form Data to be sent as a multipart form upload.

[{"key": "Example Key", "value": new Buffer("Hello World")}]
Header

A list of headers to send with the request.

User-Agent: curl/7.64.1
Max Retry Count

The maximum number of retries to attempt. Specify 0 for no retries.

0
Method

The HTTP method to use.

Query Parameter

A list of query parameters to send with the request. This is the portion at the end of the URL similar to ?key1=value1&key2=value2.

Response Type

The type of data you expect in the response. You can request json, text, or binary data.

json
Retry On All Errors

If true, retries on all erroneous responses regardless of type. This is helpful when retrying after HTTP 429 or other 3xx or 4xx errors. Otherwise, only retries on HTTP 5xx and network errors.

false
Retry Delay (ms)

The delay in milliseconds between retries. This is used when 'Use Exponential Backoff' is disabled.

0
Timeout

The maximum time that a client will await a response to its request

2000
URL

Input the path only (/templates), The base URL is already included (https://api.sendgrid.com/v3). For example, to connect to https://api.sendgrid.com/v3/templates, only /templates is entered in this field.

/templates
Use Exponential Backoff

Specifies whether to use a pre-defined exponential backoff strategy for retries. When enabled, 'Retry Delay (ms)' is ignored.

false

Send Email​

Send a single email to one or more recipients | key: sendEmail

InputNotesExample
BCC

The recipient's email address, or a comma-separated list of recipient email addresses to BCC.

example@email.com,example2@email.com
CC

The recipient's email address, or a comma-separated list of recipient email addresses to CC.

example@email.com,example2@email.com
Attachment Content

Provide attachment data to send with the email. The 'File Name' field is required when using this input and should reference the data output from a previous action.

Content Id

Provide the content Id of the attachment. This value is only required when you select 'inline'.

12345
Disposition

Specifies how you would like the attachment to be displayed.

inline
File Name

Provide a name for the file to attach. The 'Attachment Content' field is required when using this input.

reports.csv
File Type

The MIME type of the content you are attaching.

text/plain
From Email

The sender's email address.

example@email.com
From Name

The sender's name.

John Doe
HTML

The optional HTML body of the email.

Hello from <b>Acme!</b>
Multiple Attachments

Provide an array of attachments to send with the email. See https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send#request-body for more information.

Personalizations

You can use this field to overwrite multiple properties of the email. For examples of which properties to use, checkout the SendGrid docs: https://docs.sendgrid.com/for-developers/sending-email/personalizations

Reply To Email

Email To Reply To.

example@email.com
Reply To Name

Name to reply to. This field is only required when you provide a value for Reply To Email.

John Doe
Connection
Subject

The email subject line.

Hello from Acme!
Subscription Tracking

When set to true, inserts a subscription management link at the bottom of the text and HTML bodies of your email

false
Text

The text body of the email.

Here's the body of a notification.
To

The recipient's email address, or a comma-separated list of recipient email addresses.

example@email.com,example2@email.com

{
  "data": [
    {
      "body": {
        "message": "Example"
      },
      "statusCode": 200,
      "headers": {}
    },
    {}
  ]
}

Send Multiple Emails​

Send a separate email to each recipient | key: sendMultipleEmails

InputNotesExample
BCC

The recipient's email address, or a comma-separated list of recipient email addresses to BCC.

example@email.com,example2@email.com
CC

The recipient's email address, or a comma-separated list of recipient email addresses to CC.

example@email.com,example2@email.com
Attachment Content

Provide attachment data to send with the email. The 'File Name' field is required when using this input and should reference the data output from a previous action.

Content Id

Provide the content Id of the attachment. This value is only required when you select 'inline'.

12345
Disposition

Specifies how you would like the attachment to be displayed.

inline
File Name

Provide a name for the file to attach. The 'Attachment Content' field is required when using this input.

reports.csv
File Type

The MIME type of the content you are attaching.

text/plain
From Email

The sender's email address.

example@email.com
From Name

The sender's name.

John Doe
HTML

The optional HTML body of the email.

Hello from <b>Acme!</b>
Multiple Attachments

Provide an array of attachments to send with the email. See https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send#request-body for more information.

Personalizations

You can use this field to overwrite multiple properties of the email. For examples of which properties to use, checkout the SendGrid docs: https://docs.sendgrid.com/for-developers/sending-email/personalizations

Reply To Email

Email To Reply To.

example@email.com
Reply To Name

Name to reply to. This field is only required when you provide a value for Reply To Email.

John Doe
Connection
Subject

The email subject line.

Hello from Acme!
Text

The text body of the email.

Here's the body of a notification.
To

The recipient's email address, or a comma-separated list of recipient email addresses.

example@email.com,example2@email.com

{
  "data": [
    {
      "body": {
        "message": "Example"
      },
      "statusCode": 200,
      "headers": {}
    },
    {}
  ]
}

Changelog​

2025-06-18​

Added an inline data source for Contacts and Lists to enhance list selection capabilities

2025-05-27​

Added list management and contact import support for improved email campaign management