Integration reference
SendGrid Trigger and Action reference
Send email through SendGrid and start Workflows from signed delivery, engagement and account events.
Authentication
Connect a scoped SendGrid API key. Identity needs user.username.read; managed webhooks need Event Webhook settings read/create/update/delete permissions. Sending needs mail.send. FastHook stores the key encrypted. This integration uses an API key, not OAuth.
- Trigger account type:
api_key; reconnect byreplace_credentials. - Action connection type:
api_key; available modes: Connected account.
Create or reuse the account from a Trigger or Action dialog, or manage it under Settings → Connected accounts. See Authentication and permissions for scopes and access diagnostics, or Connected accounts for reuse, reconnect, revocation, and credential rotation.
Scopes and permissions
The Trigger manifest does not declare a fixed base OAuth scope list. Installation access, API credentials, or the selected event configuration can still control available resources.
Operation-specific requirements appear in the tables below. Custom event selections can add scopes dynamically, so the current Trigger or Action dialog remains authoritative for the exact consent request.
Use SendGrid as a Trigger
The current provider manifest contains 12 available Trigger definitions. Representative definitions include:
- Email Delivered
- Email Bounced
- Email Opened
- Email Link Clicked
View all 12 available Trigger definitions
| Trigger | Manifest key | Delivery | Additional scopes |
|---|---|---|---|
| Email Processed | sendgrid.processed.instant | instant | None declared |
| Email Dropped | sendgrid.dropped.instant | instant | None declared |
| Email Delivered | sendgrid.delivered.instant | instant | None declared |
| Email Deferred | sendgrid.deferred.instant | instant | None declared |
| Email Bounced | sendgrid.bounce.instant | instant | None declared |
| Email Opened | sendgrid.open.instant | instant | None declared |
| Email Link Clicked | sendgrid.click.instant | instant | None declared |
| Spam Reported | sendgrid.spamreport.instant | instant | None declared |
| Recipient Unsubscribed | sendgrid.unsubscribe.instant | instant | None declared |
| Recipient Unsubscribed from Group | sendgrid.group_unsubscribe.instant | instant | None declared |
| Recipient Resubscribed to Group | sendgrid.group_resubscribe.instant | instant | None declared |
| Account Status Changed | sendgrid.account_status_change.instant | instant | None declared |
Choose the narrowest event definition that fits the Workflow. Configure provider-specific resource and event filters in the Source dialog before adding broader Workflow Filters.
Use SendGrid Actions
The current Action manifest contains 9 operations. Representative Actions include:
- Send Email
- Get Credit Balance
- List Verified Senders
- List Event Webhooks
View all 9 available Action definitions
| Action | Manifest key | Access and auth | Manifest rate limit |
|---|---|---|---|
| Send Email | sendgrid.send_email | None declared FastHook-managed account | 1/second |
| Create Batch ID | sendgrid.create_batch_id | None declared FastHook-managed account | 1/second |
| Validate Batch ID | sendgrid.validate_batch_id | None declared FastHook-managed account | 1/second |
| Get Account Identity | sendgrid.get_account | None declared FastHook-managed account | 1/second |
| Get Credit Balance | sendgrid.get_credits | None declared FastHook-managed account | 1/second |
| Get API Key Permissions | sendgrid.get_scopes | None declared FastHook-managed account | 1/second |
| List Verified Senders | sendgrid.list_verified_senders | None declared FastHook-managed account | 1/second |
| List Event Webhooks | sendgrid.list_event_webhooks | None declared FastHook-managed account | 1/second |
| Custom API Request | sendgrid.custom_api_request | None declared FastHook-managed account | 1/second |
The Action editor reads its required permissions, fields, remote resource pickers, output schema, and rate limit from the provider manifest. Available fields can change with the selected operation and authentication mode.
Build a Workflow
- Create a Source using a SendGrid Trigger definition.
- Create a Workflow with that Source as its Trigger.
- Add the required SendGrid Action and select the connected account.
- Map Trigger or earlier-Step data into the Action fields with the field picker.
- Add a Filter, Paths, Delay, or Transformation when the route needs it.
- Activate the Workflow, produce a controlled event, and verify the run in Audit and in SendGrid.
Troubleshooting SendGrid
- The account is missing or cannot be selected
- Confirm the active FastHook team, provider, account status, and authentication mode. A disabled or revoked account cannot execute an Action.
- A resource picker is empty
- Verify that the connected provider identity can access the resource itself. OAuth consent does not add workspace, repository, channel, drive, project, base, or record permissions.
- The editor asks for additional scopes
- Reconnect the same account from the affected Trigger or Action so FastHook can request its current manifest scopes. Then reopen the editor and select the resource again.
- An active Workflow returns 401, 403, or a permission error
- Compare the selected operation’s access requirements below with the account recorded in Audit. Check provider-side membership and object access before repeating the Action.
- The provider returns 429 or a temporary 5xx
- Inspect the Step attempt and retryability in Audit. FastHook can retry temporary failures, but provider quotas and idempotency rules still apply.
Provider-specific checks
- Email Delivered means acceptance by the recipient mail server. It does not prove inbox placement or reading. Open and click events require the sender's tracking settings.
- FastHook creates a signed Event Webhook and verifies P-256 ECDSA against the timestamp and exact request body. It accepts up to 1,000 events and 2 MiB per request, with a separate deduplication receipt for each event.
- An eligible Email API plan and verified sender are required for real email sending. Sample data verifies mappings only; it is not evidence that a message was delivered.
- Mail Send accepts the official structured body, including base64 attachments. Only the global api.sendgrid.com endpoint is supported; EU regional subusers and Inbound Parse are not included.
- Disconnect removes the owned webhook and FastHook credentials. Revoke the API key separately in SendGrid if it should no longer be usable elsewhere.