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

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": "..."}