<!-- Generated by scripts/generate-llms.mjs from docs/connectors/sendgrid.md. Do not edit. -->

Source: https://qbash.com/docs/connectors/sendgrid

# Connect SendGrid

Tasks call SendGrid through `qbash.integrations.sendgrid` with an API key you store on the Connectors page. The connector reads stats, suppression lists, templates, Email Activity and Marketing Campaigns contacts. Its writes send one email, upsert contacts, add global unsubscribes, create a contact list and take contacts off a list. No method deletes anything in SendGrid.

After you connect SendGrid, you can add its tools to a [qbash MCP server](https://qbash.com/docs-markdown/mcp-servers/overview.md#package) for ChatGPT, Claude and other MCP clients, or call it from a Python task.

## Create an API key

1. Sign in to [SendGrid](https://app.sendgrid.com). To connect a subuser from a parent account, switch into that subuser in SendGrid first and create the key there. A key made on the parent account reads the parent's data.
2. Open **Settings**, then **API Keys**, and click **Create API Key**.
3. Name the key, such as "qbash tasks", and choose **Full Access** or **Custom Access**. With Custom Access, give the key the permissions in the table below for the methods your tasks call.
4. Click **Create & View** and copy the key. SendGrid shows it once, so paste it somewhere safe or straight into qbash. Keys start with `SG.`.

| Method | Permission on the key |
| --- | --- |
| `get_stats` | Stats (`stats.read`). With `categories`, Category Management stats (`categories.stats.read`) |
| `list_categories` | Category Management (`categories.read`) |
| `list_suppressions` | Suppressions, read access for the list you pass as `type` (such as `suppression.bounces.read`) |
| `list_unsubscribe_groups` | Suppressions (`asm.groups.read`) |
| `list_group_suppressions` | Suppressions (`asm.groups.suppressions.read`) |
| `list_templates`, `get_template` | Template Engine (`templates.read`) |
| `search_messages`, `get_message` | Email Activity (`email_activity.read`), plus the paid Email Activity add-on on the account |
| `search_contacts`, `get_contacts_by_emails`, `list_contact_lists`, `get_contact_import_status`, `list_single_sends`, `get_single_send_stats`, `list_segments`, `list_custom_fields` | Marketing, read access (`marketing.read`) |
| `list_verified_senders` | Sender Authentication, read access |
| `send_email` | Mail Send (`mail.send`) |
| `upsert_contacts`, `create_contact_list`, `remove_contacts_from_list` | Marketing, full access |
| `add_global_unsubscribes` | Suppressions (`asm.suppressions.global.create`) |

A key that lacks one of these still works for the methods it covers. A call it cannot make fails with a message that names the missing permission.

## Pick the region

Most accounts use **Global**, which calls `api.sendgrid.com`. Choose **EU**, which calls `api.eu.sendgrid.com`, only for a subuser created in SendGrid's EU region.

SendGrid does not offer Marketing Campaigns, Email Activity, Email Validation or Geostats to EU regional subusers ([Data Residency FAQ](https://www.twilio.com/docs/sendgrid/data-residency/faq)). On an EU credential, qbash refuses the contact, list, Single Send and Email Activity methods before calling SendGrid. Mail Send, stats, suppressions and templates work in both regions.

## Add the key in qbash

1. Open **Connectors**, then **SendGrid**, and click **Connect**.
2. Fill in **Credential Name**, such as "qbash marketing email", choose the **Region** and paste the key into **API Key**.
3. Save. qbash checks the key against the region's host and saves it only if SendGrid accepts it.
4. In the task editor, choose **Add connector** from the Package **+** menu and select the credential. See [Task resources](https://qbash.com/docs-markdown/tasks/task-editor.md#resources).

To change the region later, edit the credential and leave **API Key** blank to keep the saved key. qbash checks that key against the new region when you save.

## Send a test email from a task

`sandbox=True` asks SendGrid to validate the request without delivering it, so you can test a task before it emails anyone:

```python
result = qbash.integrations.sendgrid.send_email(
    to=["hello@qbash.com"],
    from_="hello@qbash.com",
    from_name="qbash",
    subject="qbash weekly report",
    text="This week's report is ready.",
    sandbox=True,
)
qbash.output(result)
```

A sandbox check returns `status_code` 200 and `sandbox` set to `True`. Remove `sandbox=True` to send for real. SendGrid then returns 202 with a `message_id` that `get_message` looks up in Email Activity. The `from_` address must be a verified sender or belong to a domain you authenticated in SendGrid. `list_verified_senders` shows which addresses qualify.

Reading last week's totals takes one call:

```python
from datetime import datetime, timedelta, timezone

end = datetime.now(timezone.utc).date()
report = qbash.integrations.sendgrid.get_stats(
    start_date=(end - timedelta(days=7)).isoformat(),
    end_date=end.isoformat(),
)
qbash.output(report["stats"])
```

The list methods return `next_cursor`. Pass it back as `cursor` until it is `None`. The [SDK Reference](https://qbash.com/docs-markdown/tasks/sdk-reference.md) lists every method and its parameters.

## Add test data

A new account returns empty stats and suppression lists. To fill them:

1. Send a few real emails to an inbox you own, such as `hello@qbash.com`, with `send_email` and `categories=["qbash test"]`. Sandbox sends are not delivered, so use real sends here. With open and click tracking on in SendGrid, open one email and click a link in it to record an open and a click.
2. Add a test contact with `upsert_contacts(contacts=[{"email": "hello@qbash.com", "first_name": "Sam"}])`. Create a list first with `create_contact_list(name="qbash test list")` and pass its id in `list_ids` to fill the list too.
3. For a suppression to read, add an address you own with `add_global_unsubscribes`. No method removes it, so take it off the list afterwards under **Suppressions** in SendGrid.

## Details that affect results

- `get_stats` dates are `YYYY-MM-DD` days in UTC, and `end_date` defaults to today. `get_single_send_stats` takes a `timezone` such as `Australia/Perth` when you read one Single Send.
- `created` on a suppression is unix seconds. `start_time` and `end_time` take unix seconds, a date or an ISO 8601 time, and a time without an offset is read as UTC.
- `upsert_contacts` returns a `job_id` straight away while SendGrid processes the contacts in the background. Check it with `get_contact_import_status` until `status` is `completed`. New contacts do not appear in `search_contacts` before then.
- `search_messages` and `get_message` need SendGrid's paid Email Activity add-on. Without it, SendGrid refuses the call even when the key has `email_activity.read`.
- `send_email` sends one message to everyone in `to`, `cc` and `bcc`, up to 1000 addresses, and an address that appears twice is refused. For different content per recipient, call it once per recipient. Attachments are not supported.
- SendGrid sets rate limits per endpoint. When a call gets a 429 and the limit resets within five seconds, qbash waits and retries it once. Otherwise the call fails with the reset time, and the task should wait until then before calling that endpoint again.
- `search_contacts` returns at most 50 contacts with the total `contact_count`, and SendGrid stops a search after 20 seconds.
