{"openapi":"3.1.0","info":{"title":"SendGrid (BYOK) API","version":"0.1.0","description":"SendGrid (BYOK) lets an AI assistant read your own SendGrid data through the SendGrid API with a key you supply (API key (create one with read-only access to statistics, templates and suppressions)). Read-only: 8 tools (get_global_stats, get_mailbox_provider_stats, list_templates, list_bounces, list_blocks, list_spam_reports, list_global_unsubscribes, list_suppression_groups). The BYOK key...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-sendgrid.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-sendgrid/docs"},"termsOfService":"https://connectorbay.com/byok-sendgrid/terms"},"servers":[{"url":"https://byok-sendgrid.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-sendgrid/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_global_stats":{"post":{"operationId":"get_global_stats","summary":"Get account-wide email statistics per day, week or month: requests, delivered, opens, clicks, bounces, blocks, spam repo","description":"Get account-wide email statistics per day, week or month: requests, delivered, opens, clicks, bounces, blocks, spam reports and unsubscribes. Dates are YYYY-MM-DD. SendGrid keeps detailed statistics for a limited time. Use for \"How many emails did I send and how many bounced on SendGrid last month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"description":"First day of the range, as YYYY-MM-DD, for example 2026-09-01.","maxLength":10,"title":"Start Date","type":"string"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Last day of the range, as YYYY-MM-DD (default today).","title":"End Date"},"aggregated_by":{"anyOf":[{"enum":["day","week","month"],"type":"string"},{"type":"null"}],"default":null,"description":"Group the statistics by day, week or month (default one row per day).","title":"Aggregated By"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many rows to return (1 to 500).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"How many rows to skip, for paging.","title":"Offset"}},"required":["start_date"],"title":"get_global_statsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_mailbox_provider_stats":{"post":{"operationId":"get_mailbox_provider_stats","summary":"Get email statistics split by mailbox provider (such as Gmail or Yahoo): delivered, blocks, bounces, deferred, spam repo","description":"Get email statistics split by mailbox provider (such as Gmail or Yahoo): delivered, blocks, bounces, deferred, spam reports and more. Dates are YYYY-MM-DD. SendGrid keeps detailed statistics for a limited time. Use for \"How is my email delivered to Gmail on SendGrid\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"description":"First day of the range, as YYYY-MM-DD, for example 2026-09-01.","maxLength":10,"title":"Start Date","type":"string"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Last day of the range, as YYYY-MM-DD (default today).","title":"End Date"},"aggregated_by":{"anyOf":[{"enum":["day","week","month"],"type":"string"},{"type":"null"}],"default":null,"description":"Group the statistics by day, week or month (default one row per day).","title":"Aggregated By"},"mailbox_providers":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Name of one mailbox provider to include, for example 'Gmail'. Omit for all providers.","title":"Mailbox Providers"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many rows to return.","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"How many rows to skip, for paging.","title":"Offset"}},"required":["start_date"],"title":"get_mailbox_provider_statsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_templates":{"post":{"operationId":"list_templates","summary":"List transactional email templates with id, name, generation (legacy or dynamic) and last update, 200 per page at most; ","description":"List transactional email templates with id, name, generation (legacy or dynamic) and last update, 200 per page at most; follow _metadata.next for more. Use for \"Which email templates do I have on SendGrid\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"generations":{"anyOf":[{"enum":["legacy","dynamic","legacy,dynamic"],"type":"string"},{"type":"null"}],"default":"legacy,dynamic","description":"Which template generations to list: legacy, dynamic, or 'legacy,dynamic' for both.","title":"Generations"},"page_size":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Templates per page (1 to 200).","title":"Page Size"},"page_token":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Page token from _metadata.next of the previous answer, to get the next page.","title":"Page Token"}},"title":"list_templatesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_bounces":{"post":{"operationId":"list_bounces","summary":"List email addresses on the bounce suppression list with bounce time, reason and SMTP status; filter by time range or ad","description":"List email addresses on the bounce suppression list with bounce time, reason and SMTP status; filter by time range or address prefix. Use for \"Which addresses bounced on SendGrid recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_time":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only entries created at or after this time, as a Unix timestamp in seconds.","title":"Start Time"},"end_time":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only entries created at or before this time, as a Unix timestamp in seconds.","title":"End Time"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many entries to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many entries to skip, for paging (use multiples of limit).","title":"Offset"},"email":{"anyOf":[{"maxLength":254,"type":"string"},{"type":"null"}],"default":null,"description":"Only addresses that start with this text (a prefix match), for example 'jane@'.","title":"Email"}},"title":"list_bouncesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_blocks":{"post":{"operationId":"list_blocks","summary":"List email addresses on the block list (messages the receiving server refused) with time, reason and status; filter by t","description":"List email addresses on the block list (messages the receiving server refused) with time, reason and status; filter by time range or address prefix. Use for \"Which recipients are blocking my SendGrid emails\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_time":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only entries created at or after this time, as a Unix timestamp in seconds.","title":"Start Time"},"end_time":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only entries created at or before this time, as a Unix timestamp in seconds.","title":"End Time"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many entries to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many entries to skip, for paging (use multiples of limit).","title":"Offset"},"email":{"anyOf":[{"maxLength":254,"type":"string"},{"type":"null"}],"default":null,"description":"Only addresses that start with this text (a prefix match), for example 'jane@'.","title":"Email"}},"title":"list_blocksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_spam_reports":{"post":{"operationId":"list_spam_reports","summary":"List recipients who marked a message as spam, with the time and the sending IP; filter by time range or address prefix. ","description":"List recipients who marked a message as spam, with the time and the sending IP; filter by time range or address prefix. Use for \"Who marked my SendGrid emails as spam\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_time":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only entries created at or after this time, as a Unix timestamp in seconds.","title":"Start Time"},"end_time":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only entries created at or before this time, as a Unix timestamp in seconds.","title":"End Time"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many entries to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many entries to skip, for paging (use multiples of limit).","title":"Offset"},"email":{"anyOf":[{"maxLength":254,"type":"string"},{"type":"null"}],"default":null,"description":"Only addresses that start with this text (a prefix match), for example 'jane@'.","title":"Email"}},"title":"list_spam_reportsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_global_unsubscribes":{"post":{"operationId":"list_global_unsubscribes","summary":"List addresses that unsubscribed from all email, with the time they were added; filter by time range or address prefix. ","description":"List addresses that unsubscribed from all email, with the time they were added; filter by time range or address prefix. Use for \"Who unsubscribed from all my SendGrid emails\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_time":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only entries created at or after this time, as a Unix timestamp in seconds.","title":"Start Time"},"end_time":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only entries created at or before this time, as a Unix timestamp in seconds.","title":"End Time"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many entries to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many entries to skip, for paging (use multiples of limit).","title":"Offset"},"email":{"anyOf":[{"maxLength":254,"type":"string"},{"type":"null"}],"default":null,"description":"Only addresses that start with this text (a prefix match), for example 'jane@'.","title":"Email"}},"title":"list_global_unsubscribesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_suppression_groups":{"post":{"operationId":"list_suppression_groups","summary":"List unsubscribe groups with name, description, default flag and the number of unsubscribes in each; a summary of the gr","description":"List unsubscribe groups with name, description, default flag and the number of unsubscribes in each; a summary of the group suppression lists. Use for \"How many people unsubscribed from each of my SendGrid groups\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only the unsubscribe group with this id.","title":"Id"}},"title":"list_suppression_groupsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}