Skip to main content

SendGrid Component

Send emails through SendGrid

Component key: sendgrid

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.

InputNotes
API Key
password
/ Required
apiKey
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

InputNotes
Connection
connection
/ Required
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
code
/ Required
contacts
An array of contact objects to add or update. See SendGrid docs for contact object structure.
List IDs
string
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
connection
/ Required
sendGridConnection
 
 

{
  "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
string
/ Required
name
The name of the list to create.
My New Contact List
Connection
connection
/ Required
sendGridConnection
 
 

{
  "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
string
page_size
Number of results to return per page (max 100).
10
Page Token
string
page_token
Token for fetching the next or previous page of results.
 
Connection
connection
/ Required
sendGridConnection
 
 

{
  "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
string
page_size
Number of results to return per page (max 100).
10
Page Token
string
page_token
Token for fetching the next or previous page of results.
 
Connection
connection
/ Required
sendGridConnection
 
 

{
  "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
string
/ Required
emails
Comma-separated email addresses to search for.
test1@example.com,test2@example.com
Connection
connection
/ Required
sendGridConnection
 
 

{
  "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
string
/ Required
job_id
The job ID returned from Import Contacts, Add/Update Contact, or Delete Contacts operations.
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Connection
connection
/ Required
sendGridConnection
 
 

{
  "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

InputDefaultNotesExample
Include Sample Contacts
boolean
contact_sample
false
Whether to include a sample of contacts in the response.
 
List ID
string
/ Required
list_id
The ID of the list to retrieve.
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Connection
connection
/ Required
sendGridConnection
 
 
 

{
  "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

InputDefaultNotesExample
Field Mappings
code
/ Required
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
boolean
is_compressed
false
Set to true if the CSV file will be gzip-compressed.
 
List IDs
string
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
connection
/ Required
sendGridConnection
 
 
 

{
  "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

InputDefaultNotesExample
Connection
connection
/ Required
connection
 
 
 
Data
string
data
The HTTP body payload to send to the URL.
{"exampleKey": "Example Data"}
Debug Request
boolean
debugRequest
false
Enabling this flag will log out the current request.
 
File Data
string
Key Value List
fileData
File Data to be sent as a multipart form upload.
[{key: "example.txt", value: "My File Contents"}]
File Data File Names
string
Key Value List
fileDataFileNames
File names to apply to the file data inputs. Keys must match the file data keys above.
 
Form Data
string
Key Value List
formData
The Form Data to be sent as a multipart form upload.
[{"key": "Example Key", "value": new Buffer("Hello World")}]
Header
string
Key Value List
headers
A list of headers to send with the request.
User-Agent: curl/7.64.1
Max Retry Count
string
maxRetries
0
The maximum number of retries to attempt. Specify 0 for no retries.
 
Method
string
/ Required
method
The HTTP method to use.
 
Query Parameter
string
Key Value List
queryParams
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
string
/ Required
responseType
json
The type of data you expect in the response. You can request json, text, or binary data.
 
Retry On All Errors
boolean
retryAllErrors
false
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.
 
Retry Delay (ms)
string
retryDelayMS
0
The delay in milliseconds between retries. This is used when 'Use Exponential Backoff' is disabled.
 
Timeout
string
timeout
The maximum time that a client will await a response to its request
2000
URL
string
/ Required
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
boolean
useExponentialBackoff
false
Specifies whether to use a pre-defined exponential backoff strategy for retries. When enabled, 'Retry Delay (ms)' is ignored.
 

Send Email​

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

InputDefaultNotesExample
BCC
string
bcc
The recipient's email address, or a comma-separated list of recipient email addresses to BCC.
example@email.com,example2@email.com
CC
string
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
data
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
string
contentId
Provide the content Id of the attachment. This value is only required when you select 'inline'.
12345
Disposition
string
disposition
Specifies how you would like the attachment to be displayed.
inline
File Name
string
fileName
Provide a name for the file to attach. The 'Attachment Content' field is required when using this input.
reports.csv
File Type
string
fileType
The MIME type of the content you are attaching.
text/plain
From Email
string
/ Required
fromEmail
The sender's email address.
example@email.com
From Name
string
fromName
The sender's name.
John Doe
HTML
text
html
The optional HTML body of the email.
Hello from <b>Acme!</b>
Multiple Attachments
code
multipleAttachments
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
code
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
string
replyToEmail
Email To Reply To.
example@email.com
Reply To Name
string
replyToName
Name to reply to. This field is only required when you provide a value for Reply To Email.
John Doe
Connection
connection
/ Required
sendGridConnection
 
 
 
Subject
string
/ Required
subject
The email subject line.
Hello from Acme!
Subscription Tracking
boolean
subscriptionTracking
false
When set to true, inserts a subscription management link at the bottom of the text and HTML bodies of your email
 
Text
text
/ Required
text
The text body of the email.
Here's the body of a notification.
To
string
/ Required
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

InputDefaultNotesExample
BCC
string
bcc
The recipient's email address, or a comma-separated list of recipient email addresses to BCC.
example@email.com,example2@email.com
CC
string
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
data
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
string
contentId
Provide the content Id of the attachment. This value is only required when you select 'inline'.
12345
Disposition
string
disposition
Specifies how you would like the attachment to be displayed.
inline
File Name
string
fileName
Provide a name for the file to attach. The 'Attachment Content' field is required when using this input.
reports.csv
File Type
string
fileType
The MIME type of the content you are attaching.
text/plain
From Email
string
/ Required
fromEmail
The sender's email address.
example@email.com
From Name
string
fromName
The sender's name.
John Doe
HTML
text
html
The optional HTML body of the email.
Hello from <b>Acme!</b>
Multiple Attachments
code
multipleAttachments
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
code
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
string
replyToEmail
Email To Reply To.
example@email.com
Reply To Name
string
replyToName
Name to reply to. This field is only required when you provide a value for Reply To Email.
John Doe
Connection
connection
/ Required
sendGridConnection
 
 
 
Subject
string
/ Required
subject
The email subject line.
Hello from Acme!
Text
text
/ Required
text
The text body of the email.
Here's the body of a notification.
To
string
/ Required
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": {}
    },
    {}
  ]
}