SendGrid

Overview

SendGrid is a cloud-based email delivery platform providing transactional and marketing email services, with APIs for integration, analytics, and scalability. With the SendGrid integration in SquadOS, your agents can send emails, manage contacts and lists, create dynamic templates, and monitor delivery metrics — all in an automated way.

• Official website: https://sendgrid.com/
• Composio documentation: docs.composio.dev/toolkits/sendgrid

Authentication

This tool uses an API key (API_KEY) to connect.

You will need the following fields:

Field	Required	Description
api_key	Yes	API key from your SendGrid account, used to authenticate all requests.

How to get credentials

1. Go to app.sendgrid.com and sign in to your account.
2. In the side menu, go to Settings → API Keys.
3. Click Create API Key.
4. Choose a descriptive name (e.g., squados-integration) and select the required permissions — for full access, choose Full Access; for restricted use, select only Mail Send and the necessary Marketing Campaigns permissions.
5. Click Create & View and copy the key shown. It is only displayed once — store it in a safe place.

Tip

Use a dedicated key for SquadOS with the minimum required permissions. SendGrid lets you revoke keys individually without affecting other integrations.

How to connect in SquadOS

1. Go to Tools in the side menu (/admin/tools).
2. Open the Available tab and search for SendGrid.
3. Click the card to open the details and hit Connect.
4. You’re taken to the secure connection page hosted by Composio, where you enter the API key obtained above.
5. Once done, you’re sent back to SquadOS with the account connected and the tool available to your agents. (Connection-flow details in Organization Tools.)

Available actions

Note

This integration exposes 364 actions in total. The most relevant ones are listed below; see the full list in the Composio documentation.

Send email with Twilio SendGrid

SENDGRID_SEND_EMAIL_WITH_TWILIO_SEND_GRID

The Mail Send operation uses SendGrid’s v3 API to send emails. Supports multiple recipients, attachments, dynamic templates, scheduling, and advanced tracking settings.

Input parameters

Name	Type	Required	Description
personalizations	array	Yes	An array of personalization objects, each defining recipients and email metadata.
from__email	string	No	The sender’s email address. Must be a verified sender in the SendGrid account.
from__name	string	No	Display name shown alongside the sender’s email address.
subject	string	No	The global subject line of the email. Can be overridden in personalizations.
content	array	No	Array of objects with email body content and MIME type. At least one MIME type must be included.
template_id	string	No	An email template ID. Dynamic templates start with d-.
attachments	array	No	Array of attachment objects. Each must contain Base64-encoded content, type, and filename.
send_at	integer	No	Unix timestamp to schedule the email. Cannot be more than 72 hours in the future.
batch_id	string	No	Batch ID for grouped sends, enabling cancellation or pausing of delivery.
categories	array	No	Array of category names for message grouping.
asm__group__id	integer	No	ID of the unsubscribe suppression group associated with the email.
reply__to__email	string	No	Email address where replies will be sent.
ip_pool_name	string	No	Name of the dedicated IP pool to use for sending.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Create a transactional template

SENDGRID_CREATE_A_TRANSACTIONAL_TEMPLATE

Create a new transactional email template in SendGrid. Dynamic templates use Handlebars syntax (e.g., {{name}}); legacy templates use substitution tags (e.g., -name-). Each account can create up to 300 templates.

Input parameters

Name	Type	Required	Description
name	string	Yes	The name for the new transactional template.
generation	string	No	Template type: legacy (substitution tags) or dynamic (Handlebars). Defaults to legacy.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Create a new transactional template version

SENDGRID_CREATE_A_NEW_TRANSACTIONAL_TEMPLATE_VERSION

Adds a new version to an existing transactional template, including HTML content, plain text, and subject line. Supports Handlebars syntax for dynamic templates.

Input parameters

Name	Type	Required	Description
template_id	string	Yes	The ID of the transactional template to add a version to. Dynamic templates start with d-.
name	string	Yes	Name of the transactional template version.
subject	string	Yes	Subject line of the email. Supports Handlebars substitutions.
html_content	string	No	The HTML content of the email template. Maximum of 1 MB.
plain_content	string	No	Text/plain content. If omitted and generate_plain_content is true, it is auto-generated.
active	integer	No	Set to 1 to make this version active immediately.
editor	string	No	Editor type: code or design.
test_data	string	No	JSON string with mock data for dynamic template previews.
generate_plain_content	boolean	No	If true, plain content is always generated from HTML content.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Activate template version

SENDGRID_ACTIVATE_TEMPLATE_VERSION

Activates a specific version of a transactional template, making it the default version used when sending emails. Only one version can be active per template at a time.

Input parameters

Name	Type	Required	Description
template_id	string	Yes	The ID of the transactional template. Dynamic templates start with d-.
version_id	string	Yes	The UUID of the template version to activate.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Edit a transactional template

SENDGRID_EDIT_A_TRANSACTIONAL_TEMPLATE

Updates the name of an existing transactional template. To modify the template content (HTML, subject line), use the template versions API instead.

Input parameters

Name	Type	Required	Description
template_id	string	Yes	The unique identifier of the transactional template to edit.
name	string	No	The new name for the transactional template.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Retrieve a single transactional template

SENDGRID_RETRIEVE_A_SINGLE_TRANSACTIONAL_TEMPLATE

Retrieves a single transactional template by its ID, including all associated template versions and which version is currently active.

Input parameters

Name	Type	Required	Description
template_id	string	Yes	The unique identifier of the transactional template to retrieve. Dynamic templates start with d-.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Add or update a contact

SENDGRID_ADD_OR_UPDATE_A_CONTACT

Adds or updates contacts in SendGrid Marketing Campaigns asynchronously. Contacts are matched by email, phone_number_id, external_id, or anonymous_id. Max 30,000 contacts or 6 MB per request.

Input parameters

Name	Type	Required	Description
contacts	array	Yes	An array of contact objects. Each contact must include at least one identifier (email, phone_number_id, external_id, or anonymous_id). Optional fields: first_name, last_name, city, country, etc.
list_ids	array	No	Optional array of list IDs (UUIDs) to add the contacts to.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Get a contact by ID

SENDGRID_GET_A_CONTACT_BY_ID

Retrieves the full details of a single contact by their unique ID from SendGrid Marketing Campaigns, including all standard and custom fields.

Input parameters

Name	Type	Required	Description
id	string	Yes	The unique identifier (UUID) of the contact to retrieve.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Delete contacts

SENDGRID_DELETE_CONTACTS

Deletes contacts from your SendGrid Marketing Campaigns account. This is a destructive, irreversible operation processed asynchronously. Provide ids (comma-separated UUIDs) to delete specific contacts, or set delete_all_contacts to "true" to delete all contacts.

Input parameters

Name	Type	Required	Description
ids	string	No	A comma-separated list of contact UUIDs to delete. Use this field OR delete_all_contacts, but not both.
delete_all_contacts	string	No	Set to "true" to delete ALL contacts from the account. Irreversible. Use this field OR ids, but not both.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Export contacts

SENDGRID_EXPORT_CONTACTS

Initiates an asynchronous job to export Marketing Campaigns contacts to CSV or JSON. After starting the job, poll the export status endpoint to check progress and retrieve download URLs (valid for 72 hours).

Input parameters

Name	Type	Required	Description
file_type	string	No	Export format: csv or json.
list_ids	array	No	IDs of the contact lists to export. If omitted along with segment_ids, all contacts are exported.
segment_ids	array	No	IDs of the contact segments to export.
max_file_size	integer	No	Maximum size of each export file in MB (default: 5000 MB).
notifications__email	boolean	No	If true, sends an email with the download link when the export is complete.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Create a list

SENDGRID_CREATE_A_LIST

Create a new contact list in SendGrid’s Marketing Campaigns. List names must be unique within your account. After creating the list, use the add contacts action to populate it.

Input parameters

Name	Type	Required	Description
name	string	Yes	The name of the contact list to create. Must be unique across all lists in the account.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Create a segment

SENDGRID_CREATE_A_SEGMENT

Creates a new segment in SendGrid’s Contact Database (Legacy Marketing Campaigns). Segments group contacts based on specified conditions for targeted email campaigns. Supports operators such as eq, ne, contains, gt, lt, and and/or combinations.

Input parameters

Name	Type	Required	Description
name	string	Yes	A unique name for this segment.
conditions	array	Yes	An array of condition objects defining segment membership criteria. Each condition must have field, operator, and value.
list_id	integer	No	The ID of an existing list to create this segment from. If omitted, the segment is created from the main contactdb.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Get all single sends

SENDGRID_GET_ALL_SINGLE_SENDS

Retrieve a list of your Single Sends with brief details, including their IDs. For in-depth information on a specific Single Send, use its ID at the corresponding action.

Input parameters

Name	Type	Required	Description
page_size	integer	No	Page Size
page_token	string	No	Page Token

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Create single send

SENDGRID_CREATE_SINGLE_SEND

The endpoint lets you create a Single Send draft without needing a template ID; it now uses email_config. A set send_at pre-populates the send date in the SendGrid UI, but the actual scheduling must be done through the schedule endpoint or the SendGrid UI.

Input parameters

Name	Type	Required	Description
name	string	Yes	The name of the Single Send. Must be unique.
email__config__subject	string	No	The subject line of the Single Send. Do not use with email__config__design__id.
email__config__html__content	string	No	The HTML content of the Single Send.
email__config__plain__content	string	No	The plain text content of the Single Send.
email__config__sender__id	integer	No	The ID of the verified Sender.
email__config__suppression__group__id	integer	No	The ID of the Suppression Group for unsubscribe options.
send__to__list__ids	array	No	The recipient List IDs that will receive the Single Send.
send__to__segment__ids	array	No	The recipient Segment IDs that will receive the Single Send.
send__to__all	boolean	No	Set to true to send to All Contacts.
categories	array	No	The categories to associate with this Single Send.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Retrieve all scheduled sends

SENDGRID_RETRIEVE_ALL_SCHEDULED_SENDS

The endpoint provides details of cancelled or paused scheduled sends but only if they have a batch_id. Sends scheduled without a batch_id via /mail/send won’t be listed.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Create a sender identity

SENDGRID_CREATE_A_SENDER_IDENTITY

Create a new sender identity in SendGrid. A sender identity is required to send email and represents the “from” information that recipients will see. You may create up to 100 unique sender identities.

Input parameters

Name	Type	Required	Description
nickname	string	Yes	A friendly name to identify this sender identity in the SendGrid dashboard. Not displayed to recipients.
from__name	string	Yes	The display name that will appear in the “From” field of sent emails.
from__email	string	Yes	The email address that will appear in the “From” field. This email will need to be verified.
reply__to__email	string	Yes	The email address where recipient replies will be sent.
address	string	Yes	The physical street address of the sender (required for CAN-SPAM compliance).
city	string	Yes	The city where the sender is located.
country	string	Yes	The country where the sender is located.
state	string	No	The state or province where the sender is located.
zip	string	No	The postal or ZIP code of the sender’s location.
address_2	string	No	Additional address information such as suite or apartment number.
reply__to__name	string	No	The display name for the reply-to address.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Get all sender identities

SENDGRID_GET_ALL_SENDER_IDENTITIES

This endpoint allows you to retrieve a list of all sender identities that have been created for your account.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Create a new suppression group

SENDGRID_CREATE_A_NEW_SUPPRESSION_GROUP

Create a new suppression group (unsubscribe group) to allow recipients to opt out of specific types of emails. You can create up to 200 suppression groups per account.

Input parameters

Name	Type	Required	Description
name	string	No	The name of the suppression group. Visible to recipients when managing their email preferences.
description	string	No	A brief description of the types of emails covered by this group. Visible to recipients.
is_default	boolean	No	Whether this should be the default suppression group. Defaults to false if not specified.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Add suppressions to a suppression group

SENDGRID_ADD_SUPPRESSIONS_TO_A_SUPPRESSION_GROUP

This endpoint allows you to add email addresses to an unsubscribe group. If you attempt to add suppressions to a group that has been deleted or does not exist, the suppressions will be added to the global suppressions list.

Input parameters

Name	Type	Required	Description
group_id	string	Yes	The id of the unsubscribe group that you are adding suppressions to.
recipient_emails	array	Yes	The list of email addresses to add to the suppression group.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Add recipient addresses to the global suppression group

SENDGRID_ADD_TO_GLOBAL_SUPPRESSIONS_GROUP

Adds one or more email addresses to the global suppression group. Email addresses added to this group will no longer receive any emails from your SendGrid account.

Input parameters

Name	Type	Required	Description
recipient_emails	array	Yes	A list of valid email addresses to add to the global suppression group. At least one email address is required.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Create API keys

SENDGRID_CREATE_API_KEYS

Creates a new SendGrid API key with specified permissions. The API key string is only returned once in the response — store it securely. Limit: 100 keys per account.

Input parameters

Name	Type	Required	Description
name	string	Yes	The name for this API Key. Used to identify the key in the SendGrid UI.
scopes	array	No	List of permission scopes for this API Key (e.g., mail.send, alerts.read). If omitted, the key gets Full Access permissions.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Get Email Activity CSV Download URL

SENDGRID_DOWNLOAD_CSV

Retrieves a presigned S3 URL to download a CSV file of email activity data (up to 1M events, last 30 days). Requires a Pro/Premier plan with the “30 Days Additional Email Activity History” add-on.

Input parameters

Name	Type	Required	Description
download_uuid	string	Yes	The unique identifier (UUID) for the CSV download request. Provided by SendGrid via email when the CSV file is ready.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Create a campaign

SENDGRID_CREATE_A_CAMPAIGN

This endpoint enables campaign creation, requiring a subject, sender ID, content (HTML and text suggested), and a list or segment ID for sending or scheduling, but not for initial creation.

Input parameters

Name	Type	Required	Description
title	string	Yes	The display title of your campaign. Viewable in the Marketing Campaigns UI.
subject	string	No	The subject of your campaign that recipients will see.
sender_id	integer	No	The ID of the “sender” identity that you have created.
html_content	string	No	The HTML of your marketing email.
plain_content	string	No	The plain text content of your emails.
list_ids	array	No	The IDs of the lists you are sending this campaign to.
segment_ids	array	No	The segment IDs for this campaign. Limited to 10 segments.
categories	array	No	The categories you would like associated to this campaign.
suppression_group_id	integer	No	The suppression group that this marketing email belongs to.
ip_pool	string	No	The pool of IPs to send this email from.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Send a campaign

SENDGRID_SEND_A_CAMPAIGN

Immediately sends an existing marketing campaign to its configured recipients. The campaign must be in draft status and must have a subject, sender_id, and at least one list_id or segment_id configured.

Input parameters

Name	Type	Required	Description
campaign_id	integer	Yes	The unique numeric identifier of the campaign to send immediately. The campaign must be in draft status.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.

Get a user’s account information

SENDGRID_GET_A_USER_S_ACCOUNT_INFORMATION

Retrieves the authenticated user’s SendGrid account details including account type (e.g., free, paid) and sender reputation score (0-100).

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error if any occurred during the execution of the action.
successful	boolean	Yes	Whether or not the action execution was successful.