SendGrid integration

What it does

The SendGrid integration lets your agency run a client's email program from inside a workflow. Connect a client's SendGrid API key once and your workflows can send email (from simple fields or from a dynamic template), keep Marketing Campaigns contacts and lists in sync with the client's source of truth, create and schedule Single Send campaigns, clean up suppression lists, validate addresses, and react in real time when SendGrid reports a delivery, bounce, open or click.

Connect a SendGrid account

1. Open your workspace in TaskJuice and navigate to Connections, or add the connection from any SendGrid node in the workflow editor.
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 trigger and action below. With Restricted Access, enable Mail Send for sending, Marketing for contacts, lists and Single Sends, Suppressions for bounce, block and unsubscribe lists, Template Engine for the template picker, Sender Management for the sender picker, and Mail Settings (Event Webhook) for the instant triggers.
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 for each delivery-lifecycle event: processed, delivered, deferred, dropped or bounce.
• sendgrid/engagement-event fires for each engagement event: open, click, spam report, unsubscribe, group unsubscribe or group resubscribe.
• sendgrid/contact-changed checks a Marketing Campaigns contact search on a schedule and fires with the contacts that are new or changed since the last check.
• sendgrid/list-created checks the account's lists on a schedule and fires with any new lists.

The two event triggers need no setup in SendGrid. When you publish a workflow that uses one, TaskJuice registers an Event Webhook named TaskJuice on the connected account and removes it when no published workflow needs it. SendGrid batches events, and TaskJuice starts one run per event, so you do not need a Loop node. Filter on the event field to narrow a trigger to one kind, such as bounces only. Open and click events need open and click tracking turned on in the client's SendGrid tracking settings.

The two scheduled triggers deliver each check's new records as an items list. Add a Loop node after them to handle each record on its own.

Actions

Sending

• sendgrid/send-email sends one email from simple fields: To, Cc and Bcc lists, a sender picked from your verified senders, a subject and an HTML body, or a dynamic template with its data. Add an unsubscribe group, categories or a scheduled send time if you need them.
• sendgrid/send-mail (Send Mail (Advanced)) gives you the full Mail Send request: per-recipient personalizations, a dynamic template, an unsubscribe group and base64 attachments.

Contacts and lists

• sendgrid/create-or-update-contact adds one contact, or updates the existing contact with the same email, and can add it to lists picked from a dropdown.
• sendgrid/upsert-contact adds or updates many contacts in one call.
• sendgrid/get-contact, sendgrid/search-contacts and sendgrid/list-contacts read contacts by id, by a segmentation query, or as a recent sample.
• sendgrid/delete-contacts removes contacts by id (or every contact in the account, if explicitly requested).
• sendgrid/list-lists, sendgrid/get-list, sendgrid/create-list, sendgrid/update-list and sendgrid/delete-list manage Marketing Campaigns lists.
• sendgrid/remove-contacts-from-list takes contacts off a list without deleting them.

Campaigns

• sendgrid/create-single-send creates a Single Send draft addressed to lists, segments or all contacts, from your own HTML or a saved design.
• sendgrid/schedule-single-send schedules a draft Single Send for a set time, or sends it now.

Suppressions and validation

• sendgrid/get-bounces and sendgrid/delete-bounces read and clear the bounce list.
• sendgrid/list-blocks, sendgrid/get-block and sendgrid/delete-blocks read and clear the block list.
• sendgrid/list-global-suppressions, sendgrid/get-global-suppression, sendgrid/add-global-suppressions and sendgrid/delete-global-suppression manage the global unsubscribe list.
• sendgrid/validate-email returns a Valid, Risky or Invalid verdict and a score for an address.

Known limitations

• Per-key rate limits, daily send caps and feature entitlements come from the client's SendGrid plan, not from TaskJuice. When SendGrid returns a 429, the action reports a retryable rate-limit error.
• SendGrid no longer offers a free plan, so the client needs a paid plan for the API to stay active.
• Marketing Campaigns features (contacts, lists, Single Sends, segments) are not on every plan. Without them those actions return a 403, reported as a FORBIDDEN error.
• Validate Email needs the Email Address Validation add-on (Pro plan or higher) and a key with that permission.
• Each SendGrid plan caps how many Event Webhooks an account can have. TaskJuice uses one per connected account; if the account is already at its cap, the event triggers cannot register until one is removed.
• Event deliveries are accepted on a private, unguessable URL. SendGrid's Signed Event Webhook (ECDSA signatures) is not turned on yet.
• Send Email puts every To, Cc and Bcc address in one message, so recipients see each other. Use Send Mail (Advanced) with one personalization per recipient to send individually.
• Mail Send returns 202 Accepted with an empty body. Use custom args or the X-Message-Id response header to match later events to the workflow run that sent the email.
• Inbound Parse, SendGrid's separate webhook for received email, is not part of this integration. Use a generic Webhook trigger if you need it.