SendGrid integration

What it does

The SendGrid integration lets your agency drive a client's email program from inside a workflow. Connect a client's SendGrid API key once and your workflows can send transactional or marketing email through the v3 Mail Send endpoint, keep Marketing Campaigns contacts and lists in sync with the client's source of truth, clean up bounce-suppression lists, and react in real time when SendGrid posts a batch of delivery or engagement events to the configured webhook URL.

Connect a SendGrid account

1. Open your workspace in TaskJuice and navigate to Connections.
2. Choose SendGrid and click Connect.
3. In a new tab, open the SendGrid API keys page signed in as the client (or as your agency, if the client has delegated key creation to you).
4. Click Create API Key, name it for the workspace, and pick a permission scope. Full Access works for every action below. Restricted Access works too, as long as Mail Send is enabled for transactional sends, Marketing for contact and list endpoints, and Suppressions Read for the bounce list.
5. Copy the SG. key value, paste it into TaskJuice, and save the connection.

To rotate or revoke the key, return to the SendGrid API keys page, delete the entry, create a new key, and update the TaskJuice connection.

Triggers

• sendgrid/delivery-event fires when SendGrid posts a batch of delivery-lifecycle events (processed, delivered, deferred, dropped, bounce). One POST may carry many events; the workflow receives them as a single activation with an items array, and you can iterate per event with a Loop node or score the whole cycle for digest semantics.
• sendgrid/engagement-event fires when SendGrid posts a batch of engagement events (open, click, spamreport, unsubscribe, group_unsubscribe, group_resubscribe). Same wrapping shape: one activation per POST with an items array.

Each trigger publishes an inbound URL. Paste it into SendGrid under Settings, Mail Settings, Event Webhook and set the inbound Authorization header to a shared secret you also paste into the TaskJuice trigger; SendGrid sends that exact value on every POST and TaskJuice verifies it before activating.

Actions

• sendgrid/send-mail sends a transactional or marketing email through the v3 Mail Send endpoint with one or more personalizations, optional dynamic template data, categories, and scheduled send time.
• sendgrid/list-contacts pages through Marketing Campaigns contacts using SendGrid's cursor-style page_token.
• sendgrid/upsert-contact adds or updates one or more contacts and optionally attaches them to lists. The upsert runs asynchronously on SendGrid's side and returns a job_id for polling.
• sendgrid/delete-contacts removes contacts by id (or every contact in the account, if explicitly requested).
• sendgrid/list-lists pages through every Marketing Campaigns list in the account.
• sendgrid/create-list creates a new Marketing Campaigns list.
• sendgrid/get-bounces fetches the current bounce-suppression list, optionally filtered to a time window.

Known limitations

• The integration uses SendGrid's v3 REST API with the connected key. Per-key rate limits, daily send caps, and feature entitlements are governed by the client's SendGrid plan, not by TaskJuice. When SendGrid returns a 429, the action surfaces as a retryable rate-limit error and honors the recommended backoff.
• Inbound webhook verification uses a shared HTTP Basic credential on the inbound URL (SendGrid's "Authentication" tab for the Event Webhook). SendGrid's Signed Event Webhook, which signs the payload with ECDSA P-256, is not used by this integration; treat the inbound URL itself as the secret and rotate the basic credential alongside the API key.
• Marketing Campaigns endpoints (contacts, lists) are not available on every SendGrid plan. If the connected account does not include Marketing Campaigns, those actions return a 403 and the workflow surfaces it as a FORBIDDEN error.
• The Mail Send action returns SendGrid's 202 Accepted with an empty body. Use the X-Message-Id response header or a custom_args payload to correlate downstream engagement events with the originating workflow run.
• Inbound Parse, the separate webhook surface SendGrid uses for received email, is not exposed by this integration. Subscribe to it from a generic Webhook trigger if you need it.