> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atako.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SendGrid

> Connect SendGrid to your Atako agents — 10 read and 4 write actions.

Let your agents send transactional emails, manage marketing contacts and lists, retrieve dynamic templates, and monitor email statistics via the SendGrid API.

## Connection

* **Authentication**: API key.
* **Required settings**:
  * **Region** — Use "api" (default) for global accounts, or "api.eu" for EU-resident accounts.

<Note>
  Sign in at app.sendgrid.com → Settings → API Keys → Create API Key. Name it, choose "Restricted Access", and grant at minimum: Mail Send (full access), Marketing Contacts (read/write), SSO (read only), Statistics (read only). Copy the key (starts with SG.). If your account is EU-resident, select "eu" in the Region field.

  See [SendGrid's documentation](https://app.sendgrid.com/settings/api_keys).
</Note>

## Read actions (10)

| Action                      | Description                                                                                                                                                                      |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `count_contacts`            | Retrieve the total number of marketing contacts in the account.                                                                                                                  |
| `get_global_stats`          | Retrieve global email statistics (requests, delivered, opens, clicks, bounces, etc.) for a date range. start\_date is required (YYYY-MM-DD format). end\_date defaults to today. |
| `get_list`                  | Retrieve a single marketing list by ID, including its contact count.                                                                                                             |
| `get_scopes`                | Retrieve the list of scopes (permissions) granted to the API key. Use as a connectivity probe.                                                                                   |
| `get_template`              | Retrieve a single transactional template by ID, including its versions.                                                                                                          |
| `list_bounces`              | List all bounced email addresses. Supports start\_time and end\_time (unix timestamps) for filtering, plus limit (page size) and offset pagination.                              |
| `list_global_suppressions`  | List all globally suppressed email addresses (addresses unsubscribed from all emails).                                                                                           |
| `list_lists`                | List all marketing contact lists. Supports page\_size (1-1000, default 100) and page\_token pagination.                                                                          |
| `list_templates`            | List all transactional templates. Pass generations=dynamic to retrieve only dynamic templates. Supports page\_size and page\_token pagination.                                   |
| `search_contacts_by_emails` | Retrieve up to 100 contacts matching the given email addresses (case-insensitive). emails: array of up to 100 strings.                                                           |

## Write actions (4)

| Action                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_list`               | Create a new marketing contact list. name: string (1-100 characters).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `remove_contacts_from_list` | Remove contacts from a list (async, returns a job\_id). Contacts are not deleted, only removed from the list. contact\_ids: comma-separated string of contact IDs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `send_email`                | Send a transactional email. Returns HTTP 202 with no body on success. Attachments are not supported (binary content excluded). personalizations: array of objects (each with to \[array of \{email, name?}], cc? \[array], bcc? \[array], subject?, dynamic\_template\_data?, custom\_args?, headers?, substitutions?). from: object \{email, name?}. subject: string (message-level, overridden by personalizations). content: array of objects \[\{type: string, value: string}]. reply\_to?: object \{email, name?}. template\_id?: string (starts with d- for dynamic templates). categories?: array of strings. send\_at?: unix timestamp (max 72 h). |
| `upsert_contacts`           | Add or update up to 30,000 marketing contacts (async, returns a job\_id for status checks via GET /v3/marketing/contacts/imports/\{job\_id}). contacts: array of objects, each with at least one identifier (email, phone\_number\_id, external\_id, or anonymous\_id). list\_ids?: array of list ID strings to add contacts to.                                                                                                                                                                                                                                                                                                                           |

## Permissions

Every action above must be explicitly granted to an agent before it can be used. See [Permissions](/integrations/permissions) for the grant model and [Security](/integrations/security) for how credentials are protected.