SendGrid

1. Overview

SendGrid is a cloud-based email delivery platform that allows businesses to send transactional and marketing emails with high deliverability rates. It provides a comprehensive API for managing contacts, lists, and email sending capabilities.

Through GoInsight's SendGrid node, you can seamlessly integrate email operations into your automation workflows. You can manage contacts and lists in your SendGrid Marketing Campaigns, as well as send emails programmatically.

2. Prerequisites

• Before using this node, you need to have a valid SendGrid account.
• You need to configure API credentials with appropriate permissions to perform the desired operations.

3. Credentials

For detailed instructions on how to obtain and configure credentials, please refer to our official documentation: Credential Configuration Guide.

4. Supported Operations

Summary

This node primarily operates around contacts, lists, and email sending functionality.

Operation Details

Create or Update a Contact

Adds or updates one or more contacts in SendGrid Marketing Campaigns asynchronously. Returns a job_id for status checking.

Input Parameters:

• Email: The contact's email address (primary identifier for SendGrid contacts). This field is used for duplicate checking - if a contact with the same email already exists, it will be updated; otherwise, a new contact will be created. Format: user@example.com. Example: "john.doe@company.com"

Optional Parameters:

• FirstName: The contact's first name. Optional but recommended for personalized email campaigns. Will be stored in SendGrid's first_name custom field. Example: "John"
• LastName: The contact's last name. Optional but recommended for complete contact information. Will be stored in SendGrid's last_name custom field. Example: "Doe"

Output:

• Data (object): Returns a JSON object containing the async job information from SendGrid. Structure: {"job_id": string} where job_id is the unique identifier for tracking this async operation. Use this job_id with SendGrid's job status API to check processing results. Note: The actual contact creation/update happens asynchronously after this API returns. Example: {"job_id": "job_a5f3c8e7-2d1b-4c9a-8e6f-3b2c1d4a5e6f"}
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging. 202=Accepted, 400=Bad Request, 401=Unauthorized, etc.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Delete a Contact

Deletes one or more contacts from SendGrid Marketing Campaigns. Returns HTTP 204 if successful.

Input Parameters:

• ContactIds: The list of SendGrid contact IDs to delete. IDs can be obtained via Search Contacts action.

Output:

• AllDeleted (bool): Whether all specified contacts were successfully deleted.
• FailedItems (object-array): List of failed deletion items. Each item is an object containing: 'ContactId' (string): The contact ID that failed to delete, 'HttpStatusCode' (number): The HTTP status code from the API response, 'ErrorMessage' (string): Detailed error description from the API.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Error description if any, otherwise an empty string.

Get Many Lists

Retrieves all contact lists for your SendGrid Marketing Campaigns with optional pagination controls. Returns an array of list objects and pagination metadata.

Optional Parameters:

• PageSize: Number of lists to return per page. Maximum 1000, recommended 100.
• PageToken: Pagination token to retrieve the next page of results. Leave empty for the first page. To get subsequent pages, use the 'next' token from '_metadata' object in the previous response. Example: "eyJsYXN0X2lkIjoxMjM0NTY3ODkwfQ=="

Output:

• Data (object): Full response object containing:
• result (array): List of contact lists. Each item has:
  • id (string): Unique list identifier
  • name (string): List name
  • contact_count (number): Number of contacts in the list
• _metadata (object): Pagination metadata containing:
  • count (number): Number of lists in current page
  • next (string): Token for next page (use as PageToken parameter)
  • prev (string): Token for previous page
  • self (string): Current request URL
• StatusCode (number): Operation status code: -1 (parameter validation error), 200 (success or business error, check ErrorMessage), 500 (network/system error, may retry).
• ErrorMessage (string): Error description if any, otherwise an empty string. When StatusCode is 200 and ErrorMessage is empty: operation fully succeeded. When StatusCode is 200 and ErrorMessage is not empty: business error occurred (e.g., rate limit, auth failure).
• OriginalStatusCode (number): The original HTTP status code returned by SendGrid API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging and troubleshooting. 200=success, 4xx=client error, 5xx=server error.

Get a Contact

Retrieves the full details of a specified contact by its ID in SendGrid Marketing Campaigns.

Input Parameters:

• ContactId: The ID of the SendGrid contact. Warning: This is NOT the email address. You can obtain the contact ID by calling the 'Search Contacts' or 'Get Many Contacts' action first. The ID format is typically a UUID string like '47d23ab0-d895-4359-a0f3-f763d208c3c7'.

Output:

• Data (object): The complete contact data returned by SendGrid. Contains the following core fields:
• id (string): Contact's unique identifier
• email (string): Contact's email address
• first_name (string): First name
• last_name (string): Last name
• created_at (string): Creation timestamp
• updated_at (string): Last update timestamp
• custom_fields (object): Custom field key-value pairs
• list_ids (array): Array of list IDs this contact belongs to
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.

Get a List

Retrieves the details of a specified contact list by its ID in SendGrid Marketing Campaigns. Optionally returns a sample of contacts.

Input Parameters:

• ListId: The ID of the SendGrid marketing list. This can be found in the URL of the SendGrid dashboard or obtained via the 'Get All Lists' action.

Output:

• Data (object): The complete contact list data returned by SendGrid API. Key fields: 'id' (string, list unique identifier), 'name' (string, list name), 'contact_count' (number, total contacts in list), '_metadata' (object, contains contact_count and self link).
• StatusCode (number): Operation status code: 200 (success, check ErrorMessage for business errors), -1 (parameter validation error), 500 (system error, may retry).
• OriginalStatusCode (number): The original HTTP status code returned by the SendGrid API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging. 200=success, 404=list not found, 401=invalid API key.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded. When StatusCode is 200 and ErrorMessage is not empty, it indicates a business error (e.g., list not found).

Get many Contacts

Retrieves one or more contacts from SendGrid Marketing Campaigns by their email addresses. Returns the contact details or error information for each requested email.

Optional Parameters:

• Ids: Comma-separated list of contact IDs to retrieve (e.g., 'id_123,id_456'). Leave empty to list all contacts. How to get IDs: Call 'Get many Contacts' without Ids parameter to list all contacts, or use search/filter to find specific contacts first. Supports both comma (,) and Chinese comma (，) as separators.
• PageToken: The token to retrieve the next page of results. How to use: Extract the value from '_metadata.next' field in the previous response's Data object. Leave empty for the first page. The '_metadata' object contains pagination information returned by SendGrid API.
• Count: Number of items to return per page (e.g., 50). Set to 0 to use SendGrid's default page size. This parameter controls the 'page_size' parameter in SendGrid API. Recommended range: 1-1000.

Output:

• Data (object): The complete response object from SendGrid API.

Structure:

• result (array): List of contact objects, each containing:
  • id (string): Unique contact identifier
  • email (string): Contact's email address
  • first_name (string): Contact's first name
  • last_name (string): Contact's last name
  • created_at (string): Creation timestamp
  • updated_at (string): Last update timestamp
  • Custom fields if any
• _metadata (object): Pagination metadata:
  • self (string): Current page URL
  • next (string): Next page token (use this for PageToken parameter)
  • prev (string): Previous page token
  • count (number): Total count of contacts
• StatusCode (number): Operation status code:
• 200: Success. The upstream API request completed successfully. Check ErrorMessage for business-level errors.
• -1: Parameter validation error. One or more input parameters are invalid or missing.
• 500: System error. Network timeout, connection failure, or response parsing error. The operation may be retried.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.
• When StatusCode is 200 and ErrorMessage is empty: Operation fully succeeded.
• When StatusCode is 200 and ErrorMessage is not empty: Upstream API returned a business error (e.g., invalid token, rate limit exceeded).
• When StatusCode is -1: Describes which parameter is invalid and how to fix it.
• When StatusCode is 500: Describes the system-level error (timeout, connection failure, etc.).
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default value is 0. Use this for debugging and troubleshooting.
• 0: The request did not reach the upstream API (e.g., network timeout, connection refused).
• 200/201/204: Upstream API returned success.
• 4xx: Client error from upstream (e.g., 400 Bad Request, 401 Unauthorized, 404 Not Found).
• 5xx: Server error from upstream.

Create a List

Creates a new contact list in SendGrid Marketing Campaigns. Returns the list details upon successful creation.

Input Parameters:

• Name: The name of the list to be created. The name must be unique across all lists in your SendGrid account. Maximum length is 100 characters. Use descriptive names for better list management. Example: "Newsletter Subscribers 2024" or "VIP Customers".

Output:

• Id (string): The ID of the created list. This is the unique identifier assigned by SendGrid to the newly created list. Use this ID when performing operations on this specific list (e.g., adding contacts, updating list name).
• Name (string): The name of the created list. This is the exact name you provided during creation.
• ContactCount (number): Number of contacts currently in the list (initially 0 for newly created lists).
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• OriginalStatusCode (number): The original HTTP status code returned by the upstream SendGrid API. Default 0 means the request did not reach upstream (e.g., timeout). 201=Created successfully, 400=Bad request, 401=Unauthorized. Use for debugging.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded. When StatusCode is 200 and ErrorMessage is empty: Operation fully succeeded. When StatusCode is 200 and ErrorMessage is not empty: SendGrid API returned a business error.
• CreatedAt (string): ISO8601 formatted creation timestamp indicating when the list was created in SendGrid. Example: "2024-01-15T10:30:00Z".

Delete a List

Deletes a contact list in SendGrid Marketing Campaigns. Returns HTTP 204 if successful.

Input Parameters:

• ListId: The ID of the SendGrid marketing list. This can be found in the URL of the SendGrid dashboard or obtained via the 'Get All Lists' action.
• Confirm: ⚠️ Safety Gate: Must be set to true to confirm deletion. This list will be permanently deleted and cannot be recovered. All contacts in this list will lose this list association (contacts themselves are not deleted).

Output:

• Data (object): Deletion result object. Key fields: 'job_id' (string, asynchronous deletion job identifier if applicable). Note: SendGrid DELETE list API returns HTTP 204 with no body on success.
• StatusCode (number): Operation status code: 200 (success, check ErrorMessage for business errors), -1 (parameter validation error), 500 (system error, may retry).
• OriginalStatusCode (number): The original HTTP status code returned by the SendGrid API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging. 204=success (list deleted), 404=list not found, 401=invalid API key.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded. When StatusCode is 200 and ErrorMessage is not empty, it indicates a business error (e.g., list not found, list cannot be deleted because it's in use).

Update a List

Updates the name of an existing contact list in SendGrid Marketing Campaigns. Returns the updated list details.

Input Parameters:

• ListId: The ID of the marketing list to update. Can be retrieved via the 'Get All Lists' node.
• Name: The new name for the list. This is a PATCH operation that only updates the name field. Other list properties (such as contact count) remain unchanged.

Output:

• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging.
• Data (object): The updated list object with the following structure: id (string): Unique list identifier, name (string): Updated list name, contact_count (number): Number of contacts in the list, _metadata (object): API metadata including self URL.

Send an Email

Sends an email using SendGrid's v3 Mail Send endpoint. Returns whether the request was accepted.

Input Parameters:

• FromEmail: The email address of the sender. IMPORTANT: This must be a Verified Sender identity configured in your SendGrid account. To set up: Log in to SendGrid Dashboard > Settings > Sender Authentication > Verify a Single Sender. Use the verified email address here. Example: noreply@yourcompany.com
• ToEmail: The email address of the recipient.
• Subject: The subject of the email.
• Content: The body content of the email. Note: Only text/plain is supported; HTML tags will be displayed as raw text.

Output:

• Data (object): Response data from SendGrid API. Success returns an object with status="Accepted" and message="Email queued for sending." Fields: {"status": string, "message": string}.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (may retry).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.
• OriginalStatusCode (number): The original HTTP status code returned by SendGrid API. Default 0 means the request did not reach upstream (e.g., timeout). Use for debugging. 202=Accepted, 4xx=Client error, 5xx=Server error.

5. Example Usage

This section will guide you through creating a simple workflow to send an email using SendGrid.

This example workflow consists of: Start -> [SendGrid Node] -> Answer.

Step-by-step Guide:

1. Add Tool Node:
   • In the workflow canvas, click the "+" button to add a new node.
   • In the popup panel, select the "Tools" tab.
   • Find and select "Sendgrid" from the tool list.
   • From the supported operations for SendGrid, select "Send an Email", which adds the corresponding node to the canvas.
2. Configure Node:
   • Click the "Send an Email" node, and the configuration panel will appear on the right.
   • Credential Configuration: At the top of the panel, locate the credential field. Click the dropdown menu and select your configured SendGrid credential.
   • Parameter Filling: Fill in the required input parameters:
   • FromEmail: Enter a verified sender email address from your SendGrid account, such as "noreply@yourcompany.com".
   • ToEmail: Enter the recipient's email address, for example, "recipient@example.com".
   • Subject: Enter the subject of the email, for example, "Welcome to Our Service".
   • Content: Enter the email body content, for example, "Hello! Welcome to our service. We hope you enjoy using our product."
3. Run and Verify:
   • Once all required parameters are correctly filled in, error indicators will disappear from the workflow canvas.
   • Click the "Test Run" button at the top right of the canvas to execute the workflow.
   • After successful execution, you can click the log icon at the top right to view detailed input and output for the nodes, verifying that the operation was successful.

After completing these steps, your workflow will be ready. When you click "Test Run," an email will be sent using SendGrid's API.

6. FAQs

Q: How do I verify my sender identity in SendGrid?

A: You need to log in to your SendGrid dashboard, navigate to Settings > Sender Authentication, and follow the instructions to verify either a single sender or domain authentication.

Q: Why are my emails not being delivered?

A: There could be several reasons:

• The sender email address is not verified in your SendGrid account.
• Your IP address may be blacklisted.
• Content of the email triggered spam filters.
• Recipient's mailbox is full or does not exist.

Q: What is the difference between a contact and a list in SendGrid?

A: A contact represents an individual recipient with email address and other personal information. A list is a group of contacts that allows you to organize and send emails to specific groups of people.

7. Official Documentation

Sendgrid Official API Documentation