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 for ChatGPT, Claude and other MCP clients, or call it from a Python task.
Create an API key
- Sign in to SendGrid. 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.
- Open Settings, then API Keys, and click Create API Key.
- 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.
- 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). 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
- Open Connectors, then SendGrid, and click Connect.
- Fill in Credential Name, such as "qbash marketing email", choose the Region and paste the key into API Key.
- Save. qbash checks the key against the region's host and saves it only if SendGrid accepts it.
- In the task editor, choose Add connector from the Package + menu and select the credential. See Task 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:
result = qbash.integrations.sendgrid.send_email(
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:
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 lists every method and its parameters.
Add test data
A new account returns empty stats and suppression lists. To fill them:
- Send a few real emails to an inbox you own, such as
[email protected], withsend_emailandcategories=["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. - Add a test contact with
upsert_contacts(contacts=[{"email": "[email protected]", "first_name": "Sam"}]). Create a list first withcreate_contact_list(name="qbash test list")and pass its id inlist_idsto fill the list too. - 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_statsdates areYYYY-MM-DDdays in UTC, andend_datedefaults to today.get_single_send_statstakes atimezonesuch asAustralia/Perthwhen you read one Single Send.createdon a suppression is unix seconds.start_timeandend_timetake unix seconds, a date or an ISO 8601 time, and a time without an offset is read as UTC.upsert_contactsreturns ajob_idstraight away while SendGrid processes the contacts in the background. Check it withget_contact_import_statusuntilstatusiscompleted. New contacts do not appear insearch_contactsbefore then.search_messagesandget_messageneed SendGrid's paid Email Activity add-on. Without it, SendGrid refuses the call even when the key hasemail_activity.read.send_emailsends one message to everyone into,ccandbcc, 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_contactsreturns at most 50 contacts with the totalcontact_count, and SendGrid stops a search after 20 seconds.