Skip to main content

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​

  1. 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.
  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..
MethodPermission on the key
get_statsStats (stats.read). With categories, Category Management stats (categories.stats.read)
list_categoriesCategory Management (categories.read)
list_suppressionsSuppressions, read access for the list you pass as type (such as suppression.bounces.read)
list_unsubscribe_groupsSuppressions (asm.groups.read)
list_group_suppressionsSuppressions (asm.groups.suppressions.read)
list_templates, get_templateTemplate Engine (templates.read)
search_messages, get_messageEmail 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_fieldsMarketing, read access (marketing.read)
list_verified_sendersSender Authentication, read access
send_emailMail Send (mail.send)
upsert_contacts, create_contact_list, remove_contacts_from_listMarketing, full access
add_global_unsubscribesSuppressions (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​

  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.

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:

  1. Send a few real emails to an inbox you own, such as [email protected], 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": "[email protected]", "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.