Send transactional email and manage Marketing Campaigns contacts via the SendGrid v3 API.

Provided free and as is, without warranty of any kind — including merchantability, fitness for a particular purpose, and the accuracy or completeness of any result. See the licence. You are responsible for checking what this produces before relying on it.

SendGrid

Send transactional email and manage Marketing Campaigns contacts through the SendGrid v3 API (https://api.sendgrid.com/v3).

This is a self-contained InTouch tool (credentialBased: false) — pass your SendGrid API key as the apiKey input. Authentication uses the standard Authorization: Bearer <apiKey> header. Implemented with the Python standard library only (no third-party packages).

Operations

operation	SendGrid endpoint	What it does
`send-mail`	`POST /v3/mail/send`	Send a plain-text transactional email. Returns `202 Accepted` on success.
`upsert-contacts`	`PUT /v3/marketing/contacts`	Add or update (upsert) one or more contacts; optionally add them to lists. Returns a `job_id`.
`search-contacts`	`POST /v3/marketing/contacts/search/emails`	Look up contacts by one or more email addresses.
`get-contact`	`GET /v3/marketing/contacts/{id}`	Retrieve a single contact by its SendGrid contact ID.
`get-lists`	`GET /v3/marketing/lists`	List all Marketing Campaigns contact lists.

Inputs

input	Used by	Description
`apiKey` (required)	all	SendGrid API key.
`operation` (required)	all	One of the operations above.
`to`	send-mail	Recipient email address.
`from`	send-mail	Verified sender email address.
`subject`	send-mail	Subject line.
`body`	send-mail	Plain-text body.
`contacts`	upsert-contacts	JSON array of contact objects.
`listIds`	upsert-contacts	Optional comma-separated list IDs.
`emails`	search-contacts	Comma-separated email addresses.
`contactId`	get-contact	SendGrid contact ID.

Outputs

result — the response body (JSON string for JSON responses; for a successful send-mail a synthesized {"sent": true, "to": ...}).
status — the HTTP status code as a string (202, 200, 400, 401, ...).

The tool never throws on a 4xx/5xx HTTP response — it returns the status and SendGrid's error JSON in result so a job can branch on it. Only a transport-level failure (DNS/timeout/refused) fails the step.

Getting an API key

Sign in at https://app.sendgrid.com.
Go to Settings → API Keys → Create API Key.
Give it Mail Send permission (for send-mail) and/or Marketing permission (for the contact operations).
Copy the key (shown once) and pass it as apiKey.

You must also have a verified sender identity (single sender or authenticated domain) for the from address, or send-mail returns 403.

Examples

Send an email

apiKey:    SG.xxxxxxxx
operation: send-mail
to:        [email protected]
from:      [email protected]
subject:   Nightly report ready
body:      Your report finished at 02:00. No errors.

→ status: 202, result: {"sent": true, "to": "[email protected]"}

Add/update a contact and put it on lists

apiKey:    SG.xxxxxxxx
operation: upsert-contacts
contacts:  [{"email":"[email protected]","first_name":"Alex","last_name":"Bloggs"}]
listIds:   8f9d2a1b-1111-2222-3333-444455556666

→ status: 202, result: {"job_id": "..."}

Publishes

The keys a later task may reference as {{taskName.key}}. Referencing anything not listed here resolves to nothing at run time.

error
result
status

Input Properties

Every property this tool accepts, from its own tool.iml.

Property	Type	Required	Default	Description
`apiKey`	string	yes	—	DEPRECATED — bind an API Key credential to the task with `credentialName` instead. A key pasted here is stored in the workflow definition in clear and appears in every export of it. Still honoured for workflows built before the change.
`operation`	string	yes	—	One of: send-mail, upsert-contacts, search-contacts, get-contact, get-lists
`to`	string	no	—	send-mail: recipient email address.
`from`	string	no	—	send-mail: verified sender email address (must be a SendGrid verified sender/domain).
`subject`	string	no	—	send-mail: email subject line.
`contacts`	string	no	—	upsert-contacts: JSON array of contact objects, e.g. [{"email":"[email protected]","first_name":"A"}].
`listIds`	string	no	—	upsert-contacts: optional comma-separated SendGrid list IDs to add the contacts to.
`emails`	string	no	—	search-contacts: comma-separated email addresses to look up.
`contactId`	string	no	—	get-contact: the SendGrid contact ID to retrieve.