SendGrid Suppressions

Email suppression lists. Manage unsubscribe groups and their members, and read blocks, bounces, spam reports, and bad addresses.

Property	Value
Slug	`sendgrid_suppressions`
Definition version	`0.1.0`
Base URL	`https://api.sendgrid.com`
Auth schemes	`api_key`
Action tools	22
By class	18 read, 4 write
Triggers	0
Provider rate limit	not declared, so outbound calls are unpaced

Measured routing accuracy

34 golden cases replayed through the router over the whole index: measured over corpus ea4f12ad2948 (65 toolkits, 2283 tools indexed and 13 declared uncallable), 22 cases written by hand and 12 cases from the paraphrase pass. A case counts as top-1 when its gold tool ranked first and top-8 when it reached the slate at all.

Measure	Cases	Share
top-1	22/34	64.7%
top-8	31/34	91.2%

The sweep is offline: the reranker is a deterministic identity fake that returns candidates in the order retrieval produced them, so top-1 measures retrieval order rather than a reranked slate. just eval-live measures the same cases through the live reranker.

Authentication

Connect an entity with ConnectionsService.InitiateConnection, naming this toolkit's slug. Credentials stay in the connections vault; callers hold connected-account ids only.

`api_key`

Property	Value
Placement	`header`
Name	`Authorization`
Rendered as	`Bearer {key}`

Submit the key with ConnectionsService rather than putting it in a request; it is sealed at rest and never returned.

Tools

22 action tools. The catalog-wide slug is sendgrid_suppressions.<tool>, which is what search_tools returns and call_tool takes.

`sendgrid_suppressions.list_asm_group`

List your SendGrid unsubscribe groups: the opt-out categories a recipient can unsubscribe from, such as newsletters or receipts. Use to see which unsubscribe buckets exist on the account. Calls GET /v3/asm/groups.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/asm/groups.

Arguments:

Argument	Type	Required	Notes
`id`	integer	no	The ID of the suppression group(s) you want to retrieve.
`on_behalf_of`	string	no	The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header...

Also retrieved by: "what unsubscribe categories do I have", "show my opt-out buckets", "which newsletter groups can people leave".

`sendgrid_suppressions.creat_asm_group`

Create a new SendGrid unsubscribe group: a named opt-out category recipients can leave, for example a newsletter or promotions bucket. Calls POST /v3/asm/groups.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v3/asm/groups.

Arguments:

Argument	Type	Required	Notes
`description`	string	no	A brief description of your suppression group. Required when creating a group.
`is_default`	boolean	no	Indicates if you would like this to be your default suppression group.
`name`	string	no	The name of your suppression group. Required when creating a group.
`on_behalf_of`	string	no	The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header...

Result fields (the payload is trimmed to these before it reaches the model):

Field	Type	Notes
`description`	string	A brief description of the suppression group.
`id`	integer	The ID of the suppression group.
`is_default`	boolean	Indicates if this is the default suppression group.
`name`	string	The name of the suppression group.

Also retrieved by: "set up a new opt-out category", "add an unsubscribe bucket for newsletters", "make a new group people can leave".

`sendgrid_suppressions.get_asm_group`

Read one SendGrid unsubscribe group by its id: the name, description, and opt-out count of a single category. Calls GET /v3/asm/groups/{group_id}.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/asm/groups/{{params.group_id}}.

Arguments:

Argument	Type	Required	Notes
`group_id`	string	yes	The ID of the suppression group you would like to retrieve.
`on_behalf_of`	string	no	The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header...

Result fields (the payload is trimmed to these before it reaches the model):

Field	Type	Notes
`description`	string	A brief description of your suppression group. Required when creating a group.
`id`	integer	The ID of the suppression group.
`is_default`	boolean	Indicates if you would like this to be your default suppression group.
`name`	string	The name of your suppression group. Required when creating a group.
`unsubscribes`	integer	The number of unsubscribes, or suppressions, in this group.

Also retrieved by: "details of one opt-out category by id", "read a single unsubscribe bucket", "show the name and count for one category".

`sendgrid_suppressions.update_asm_group`

Edit a SendGrid unsubscribe group: rename an opt-out category, change its description, or set it as the default. Calls PATCH /v3/asm/groups/{group_id}.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls PATCH /v3/asm/groups/{{params.group_id}}.

Arguments:

Argument	Type	Required	Notes
`description`	string	no	A brief description of your suppression group. Required when creating a group.
`group_id`	string	yes	The ID of the suppression group you would like to retrieve.
`is_default`	boolean	no	Indicates if you would like this to be your default suppression group.
`name`	string	no	The name of your suppression group. Required when creating a group.
`on_behalf_of`	string	no	The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header...

Result fields (the payload is trimmed to these before it reaches the model):

Field	Type	Notes
`description`	string	A description of the suppression group.
`id`	number	The id of the suppression group.
`is_default`	boolean	Indicates if this is the default suppression group. Defaults to false.
`name`	string	The name of the suppression group. Each group created by a user must have a unique name.
`unsubscribes`	integer	The unsubscribes associated with this group.

Also retrieved by: "rename an opt-out category", "edit an unsubscribe bucket's description", "make a category the default".

`sendgrid_suppressions.list_suppression_from_asm_group`

List the addresses opted out of one SendGrid unsubscribe group: everyone who left that single category. Calls GET /v3/asm/groups/{group_id}/suppressions.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/asm/groups/{{params.group_id}}/suppressions.

Arguments:

Argument	Type	Required	Notes
`group_id`	string	yes	The id of the unsubscribe group that you are adding suppressions to.
`on_behalf_of`	string	no	The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header...

Also retrieved by: "who left one unsubscribe category", "everyone opted out of a single group", "which recipients dropped this mail type".

`sendgrid_suppressions.add_suppression_to_asm_group`

Opt email addresses out of one SendGrid unsubscribe group: add recipients to a single opt-out category so they stop receiving that kind of mail. Calls POST /v3/asm/groups/{group_id}/suppressions.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v3/asm/groups/{{params.group_id}}/suppressions.

Arguments:

Argument	Type	Required	Notes
`group_id`	string	yes	The id of the unsubscribe group that you are adding suppressions to.
`on_behalf_of`	string	no	The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header...
`recipient_emails`	array of string	yes	The array of email addresses to add or find.

Result fields (the payload is trimmed to these before it reaches the model):

Field	Type	Notes
`recipient_emails`	array of string	The email addresses you added to the unsubscribe group

Also retrieved by: "opt these people out of one category", "unsubscribe recipients from a single bucket", "stop this kind of mail for these addresses".

`sendgrid_suppressions.search_suppression_from_asm_group`

Check which addresses are unsubscribed from one SendGrid suppression group: hand over a list of email addresses and get back only the ones opted out of that group. Calls POST /v3/asm/groups/{group_id}/suppressions/search.

Class read (reads only). No scopes beyond the connection's defaults. Calls POST /v3/asm/groups/{{params.group_id}}/suppressions/search.

Arguments:

Argument	Type	Required	Notes
`group_id`	string	yes	The ID of the suppression group that you would like to search.
`on_behalf_of`	string	no	The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header...
`recipient_emails`	array of string	yes	The array of email addresses to add or find.

Also retrieved by: "which of these addresses opted out of the group", "check a list of emails against one unsubscribe group", "has this customer opted out of a mail category".

`sendgrid_suppressions.list_asm_suppression`

List every SendGrid group unsubscribe: each address that opted out, and which suppression group it opted out of. Calls GET /v3/asm/suppressions.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/asm/suppressions.

Arguments:

Argument	Type	Required	Notes
`on_behalf_of`	string	no	The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header...

Also retrieved by: "everyone who opted out of any mail category", "all group unsubscribes across the account", "who is opted out and from what".

`sendgrid_suppressions.create_global_suppression`

Block addresses from all SendGrid mail: add recipients to the global do-not-mail list so they never receive any message, regardless of category. Calls POST /v3/asm/suppressions/global.

Class write (writes, no confirmation needed). No scopes beyond the connection's defaults. Calls POST /v3/asm/suppressions/global.

Arguments:

Argument	Type	Required	Notes
`on_behalf_of`	string	no	The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header...
`recipient_emails`	array of string	yes	The array of email addresses to add or find.

Result fields (the payload is trimmed to these before it reaches the model):

Field	Type	Notes
`recipient_emails`	array of string	The email addresses that are globally suppressed

Also retrieved by: "block these addresses from all mail", "add recipients to the do-not-mail list", "stop every message to these people".

`sendgrid_suppressions.get_global_suppression`

Check whether one address is on the SendGrid global do-not-mail list: is this recipient permanently blocked from all mail. Calls GET /v3/asm/suppressions/global/{email}.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/asm/suppressions/global/{{params.email}}.

Arguments:

Argument	Type	Required	Notes
`email`	string	yes	The email address of the global suppression you want to retrieve. Or, if you want to check if an email address is on the global suppressions list, enter that email address here.
`on_behalf_of`	string	no	The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header...

Result fields (the payload is trimmed to these before it reaches the model):

Field	Type	Notes
`recipient_email`	string (email)	The email address that is globally suppressed. This will be an empty object if the email address you included in your call is not globally suppressed.

Also retrieved by: "is this address blocked from all mail", "check the do-not-mail list for one person", "is this recipient permanently opted out".

`sendgrid_suppressions.get_asm_suppression`

Show which unsubscribe categories one address has left: every SendGrid opt-out group a recipient has unsubscribed from. Calls GET /v3/asm/suppressions/{email}.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/asm/suppressions/{{params.email}}.

Arguments:

Argument	Type	Required	Notes
`email`	string	yes	The email address that you want to search suppression groups for.
`on_behalf_of`	string	no	The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header...

Result fields (the payload is trimmed to these before it reaches the model):

Field	Type	Notes
`suppressions`	array of object	The array of suppression groups.
`suppressions[].description`	string	The description of the suppression group.
`suppressions[].id`	integer	The id of the suppression group.
`suppressions[].is_default`	boolean	Indicates if the suppression group is set as the default.
`suppressions[].name`	string	The name of the suppression group.
`suppressions[].suppressed`	boolean	Indicates if the given email address is suppressed for this group.

Also retrieved by: "what has this recipient opted out of", "which mail categories did someone leave", "is a customer unsubscribed from anything".

`sendgrid_suppressions.list_suppression_block`

List blocked addresses: recipients the mail server temporarily refused, usually for a full mailbox or a reputation problem. Calls GET /v3/suppression/blocks.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/suppression/blocks.

Arguments:

Argument	Type	Required	Notes
`email`	string	no	Specifies which records to return based on the records' associated email addresses. For example, `sales` returns records with email addresses that start with 'sales', such as...
`end_time`	integer	no	The end of the time range when a blocked email was created (inclusive). This is a unix timestamp.
`limit`	integer	no	`limit` sets the page size, i.e. maximum number of items from the list to be returned for a single API request. If omitted, the default page size is used. The maximum page size for this endpoint is...
`offset`	integer	no	The number of items in the list to skip over before starting to retrieve the items for the requested page. The default `offset` of `0` represents the beginning of the list, i.e. the start of the... Defaults to 0.
`on_behalf_of`	string	no	The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header...
`start_time`	integer	no	The start of the time range when a blocked email was created (inclusive). This is a unix timestamp.

Also retrieved by: "which addresses were temporarily refused", "show recipients the server would not accept", "what mail was held back for reputation".

`sendgrid_suppressions.get_suppression_block`

Look up one blocked address: whether a single recipient was temporarily refused by the mail server. Calls GET /v3/suppression/blocks/{email}.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/suppression/blocks/{{params.email}}.

Arguments:

Argument	Type	Required	Notes
`email`	string (email)	yes	The email address of the specific block.
`on_behalf_of`	string	no	The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header...

Also retrieved by: "was this one address temporarily refused", "check the temporary refusal list for a person", "look up a single held-back recipient".

`sendgrid_suppressions.list_suppression_bounces`

List bounced messages: addresses the recipient mail server rejected or returned as undeliverable. Use to see delivery failures. Calls GET /v3/suppression/bounces.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/suppression/bounces.

Arguments:

Argument	Type	Required	Notes
`Accept`	string	yes	Defaults to application/json.
`email`	string	no	Specifies which records to return based on the records' associated email addresses. For example, `sales` returns records with email addresses that start with 'sales', such as...
`end_time`	integer	no	Refers end of the time range in unix timestamp when a bounce was created (inclusive).
`limit`	integer	no	`limit` sets the page size, i.e. maximum number of items from the list to be returned for a single API request. If omitted, the default page size is used. The maximum page size for this endpoint is...
`offset`	integer	no	The number of items in the list to skip over before starting to retrieve the items for the requested page. The default `offset` of `0` represents the beginning of the list, i.e. the start of the... Defaults to 0.
`on_behalf_of`	string	no	The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header...
`start_time`	integer	no	Refers start of the time range in unix timestamp when a bounce was created (inclusive).

Also retrieved by: "which messages were rejected as undeliverable", "show returned mail", "what addresses bounced".

`sendgrid_suppressions.list_suppression_bounces_classifications`

Bounce totals by reason for a SendGrid account: how many messages bounced each day for each cause, such as an invalid address, a full mailbox, or reputation. Calls GET /v3/suppression/bounces/classifications.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/suppression/bounces/classifications.

Arguments:

Argument	Type	Required	Notes
`Accept`	string, one of application/json, text/csv	yes	Specifies the content type to be returned by this endpoint. You can choose to receive CSV-formatted data by passing "text/csv" in the header.
`end_date`	string	no	The end of the time range, in YYYY-MM-DD format, when a bounce was created (inclusive).
`on_behalf_of`	string	no	The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header...
`start_date`	string	no	The start of the time range, in YYYY-MM-DD format, when a bounce was created (inclusive).

Result fields (the payload is trimmed to these before it reaches the model):

Field	Type	Notes
`result`	array of object
`result[].date`	string
`result[].stats`	array

Also retrieved by: "why are our emails bouncing", "daily bounce counts split by cause", "how many messages hit full mailboxes".

`sendgrid_suppressions.get_suppression_bounces_classifications`

Bounce totals for one SendGrid bounce reason, by day and domain: how many messages bounced for that single cause, and which receiving domains they went to. Calls GET /v3/suppression/bounces/classifications/{classification}.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/suppression/bounces/classifications/{{params.classification}}.

Arguments:

Argument	Type	Required	Notes
`Accept`	string, one of application/json, text/csv	yes	Specifies the content type to be returned by this endpoint. You can choose to receive CSV-formatted data by passing "text/csv" in the header.
`classification`	string, one of Content, Frequency or Volume Too High, Invalid Address, Mailbox Unavailable, Reputation, Technical Failure, Unclassified	yes	The classification you want to filter by. Possible values are: `Content`, `Frequency or Volume Too High`, `Invalid Address`, `Mailbox Unavailable`, `Reputation`, `Technical Failure`, `Unclassified`.
`end_date`	string	no	The end of the time range, in YYYY-MM-DD format, when a bounce was created (inclusive).
`on_behalf_of`	string	no	The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header...
`start_date`	string	no	The start of the time range, in YYYY-MM-DD format, when a bounce was created (inclusive).

Result fields (the payload is trimmed to these before it reaches the model):

Field	Type	Notes
`result`	array of object
`result[].date`	string
`result[].stats`	array

Also retrieved by: "which domains reject us for one reason", "daily counts for a single bounce cause", "is gmail bouncing us more than others".

`sendgrid_suppressions.get_suppression_bounces`

Look up why one address bounced: the reason a message to a single recipient was rejected or returned undelivered. Calls GET /v3/suppression/bounces/{email}.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/suppression/bounces/{{params.email}}.

Arguments:

Argument	Type	Required	Notes
`email`	string (email)	yes	The email address of the specific bounce you would like to retrieve
`on_behalf_of`	string	no	The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header...

Also retrieved by: "why did mail to this address come back", "reason one recipient was rejected", "look up a single undelivered message".

`sendgrid_suppressions.list_invalid_email`

List invalid recipient addresses: mailboxes that are malformed or do not exist, so mail can never reach them. Calls GET /v3/suppression/invalid_emails.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/suppression/invalid_emails.

Arguments:

Argument	Type	Required	Notes
`email`	string	no	This parameter allows you to filter results by email address. Only invalid addresses matching an address passed in this parameter will be returned.
`end_time`	integer	no	Refers end of the time range in unix timestamp when an invalid email was created (inclusive).
`limit`	integer	no	`limit` sets the page size, i.e. maximum number of items from the list to be returned for a single API request. If omitted, the default page size is used. The maximum page size for this endpoint is...
`offset`	integer	no	The number of items in the list to skip over before starting to retrieve the items for the requested page. The default `offset` of `0` represents the beginning of the list, i.e. the start of the... Defaults to 0.
`on_behalf_of`	string	no	The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header...
`start_time`	integer	no	Refers start of the time range in unix timestamp when an invalid email was created (inclusive).

Also retrieved by: "which mailboxes do not exist", "show malformed recipient addresses", "where can mail never be delivered".

`sendgrid_suppressions.get_invalid_email`

Look up one invalid recipient address: whether a single malformed or non-existent mailbox is on the list. Calls GET /v3/suppression/invalid_emails/{email}.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/suppression/invalid_emails/{{params.email}}.

Arguments:

Argument	Type	Required	Notes
`email`	string	yes	The specific email address of the invalid email entry that you want to retrieve.
`on_behalf_of`	string	no	The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header...

Also retrieved by: "is this address on the bad mailbox list", "did we mark one recipient as undeliverable", "check whether a single mailbox is invalid".

`sendgrid_suppressions.list_spam_report`

List spam complaints: recipients who flagged your messages as junk. Use to see who reported mail as spam. Calls GET /v3/suppression/spam_reports.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/suppression/spam_reports.

Arguments:

Argument	Type	Required	Notes
`email`	string	no	Specifies which records to return based on the records' associated email addresses. For example, `sales` returns records with email addresses that start with 'sales', such as...
`end_time`	integer	no	The end of the time range when a spam report was created (inclusive). This is a unix timestamp.
`limit`	integer	no	`limit` sets the page size, i.e. maximum number of items from the list to be returned for a single API request. If omitted, the default page size is used. The maximum page size for this endpoint is...
`offset`	integer	no	The number of items in the list to skip over before starting to retrieve the items for the requested page. The default `offset` of `0` represents the beginning of the list, i.e. the start of the... Defaults to 0.
`on_behalf_of`	string	no	The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header...
`start_time`	integer	no	The start of the time range when a spam report was created (inclusive). This is a unix timestamp.

Also retrieved by: "who marked my mail as junk", "recipients who reported spam", "show junk complaints".

`sendgrid_suppressions.get_spam_report`

Look up one spam complaint: whether a single recipient flagged your mail as junk. Calls GET /v3/suppression/spam_reports/{email}.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/suppression/spam_reports/{{params.email}}.

Arguments:

Argument	Type	Required	Notes
`email`	string (email)	yes	The email address of a specific spam report that you want to retrieve.
`on_behalf_of`	string	no	The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header...

Also retrieved by: "did this person mark us as junk", "check one recipient for a spam complaint", "was a single address a junk report".

`sendgrid_suppressions.list_global_suppression`

List every address on the SendGrid global do-not-mail list: recipients permanently blocked from all mail. Calls GET /v3/suppression/unsubscribes.

Class read (reads only). No scopes beyond the connection's defaults. Calls GET /v3/suppression/unsubscribes.

Arguments:

Argument	Type	Required	Notes
`email`	string	no	Specifies which records to return based on the records' associated email addresses. For example, `sales` returns records with email addresses that start with 'sales', such as...
`end_time`	integer	no	Refers end of the time range in unix timestamp when an unsubscribe email was created (inclusive).
`limit`	integer	no	`limit` sets the page size, i.e. maximum number of items from the list to be returned for a single API request. If omitted, the default page size is used. The maximum page size for this endpoint is...
`offset`	integer	no	The number of items in the list to skip over before starting to retrieve the items for the requested page. The default `offset` of `0` represents the beginning of the list, i.e. the start of the... Defaults to 0.
`on_behalf_of`	string	no	The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header...
`start_time`	integer	no	Refers start of the time range in unix timestamp when an unsubscribe email was created (inclusive).

Also retrieved by: "who is blocked from all mail", "show the do-not-mail list", "every permanently opted-out address".