--- title: "client.suppressions()" description: "Every method in this namespace: its signature, its parameters, what it returns and an example." url: "https://openemail.uk/docs/java/reference/suppressions" area: "Java" category: "Reference" --- # client.suppressions() Every method in this namespace: its signature, its parameters, what it returns and an example. ## Methods The addresses this workspace will not send to: hard bounces, complaints and the ones you block by hand. ### `suppressions().list` List one page of the suppression list ```java Page list(RequestOptions options) ``` Returns one page of the addresses this workspace will not send to, newest first: every address that bounced hard, complained, or was added by hand. `listAll` collects every page and `iterate` walks them lazily. A send to a suppressed address is refused for that recipient before anything leaves, and a message whose recipients are all suppressed fails outright. The list belongs to the whole workspace, so a key limited to some addresses reads all of it, and a row names the recipient, never which of your addresses sent to it. `removable` says whether `remove` will take the address off. A hard bounce is permanent here, because the address could not take mail. A complaint or a manual entry can be removed. Scopes: `settings:read`. **Parameters** - `options.q` (`String`): Searches the address, the reason and the detail. Words match loosely, and a close spelling is tried when nothing matches exactly. - `options.reason` (`String`): Keeps one kind: `bounce`, `complaint` or `manual`, as in `uk.openemail.constants.SuppressionReasons`. - `options.limit` (`int`): Page size, from 1 to 100. The server defaults to 25. - `options.cursor` (`String`): The `nextCursor` of the previous page. Leave it out for the first page. - `options.apiKey` (`String`): Overrides the client API key for this call only. **Returns** A `Page` of maps with `items`, `hasMore` and `nextCursor`. Each item has `id`, `email`, `reason`, `detail`, `removable` and `createdAt`. **Example** ```java Page page = client.suppressions().list(RequestOptions.of("reason", "complaint")); for (Map suppression : page) { System.out.println(suppression.get("id") + " " + suppression.get("email")); } if (page.hasMore()) { System.out.println("Next page: " + page.nextCursor()); } ``` **Notes** - Needs `settings:read`, the scope the Blocked addresses screen in Settings is gated on. - The cursor is opaque and holds where the last row sat, so an address removed between pages never breaks the walk. A cursor this list did not hand out is a 400 `invalid_cursor`. Also available in: API [`GET /suppressions`](https://openemail.uk/docs/api/reference/suppressions#get-suppressions); TypeScript [`suppressions.list()`](https://openemail.uk/docs/sdk/reference/suppressions#list); Python [`suppressions.list()`](https://openemail.uk/docs/python/reference/suppressions#list); Ruby [`suppressions.list`](https://openemail.uk/docs/ruby/reference/suppressions#list); PHP [`suppressions->list`](https://openemail.uk/docs/php/reference/suppressions#list); Go [`Suppressions.List`](https://openemail.uk/docs/go/reference/suppressions#list); C# [`Suppressions.ListAsync`](https://openemail.uk/docs/csharp/reference/suppressions#list); CLI [`openemail suppressions list`](https://openemail.uk/docs/cli/reference/suppressions#suppressions-list). ### `suppressions().listAll` Collect the whole suppression list into one list ```java List> listAll(RequestOptions options) ``` Walks every page of `list` and returns every suppressed address, newest first. One request per page, with the same filters on each. Scopes: `settings:read`. **Parameters** - `options.q` (`String`): Searches the address, the reason and the detail. Words match loosely, and a close spelling is tried when nothing matches exactly. - `options.reason` (`String`): Keeps one kind: `bounce`, `complaint` or `manual`, as in `uk.openemail.constants.SuppressionReasons`. - `options.limit` (`int`): Page size for each request, from 1 to 100. The server defaults to 25. - `options.cursor` (`String`): Starts the walk after this cursor instead of the first page. - `options.apiKey` (`String`): Overrides the client API key for every page of this walk. **Returns** A list of maps holding every suppressed address, each with the fields `list` returns. **Example** ```java List> all = client.suppressions().listAll(RequestOptions.create().limit(100)); for (Map item : all) { System.out.println(item.get("id") + " " + item.get("email")); } ``` **Notes** - If any page fails the call throws and the rows already fetched are discarded. Also available in: API [`GET /suppressions`](https://openemail.uk/docs/api/reference/suppressions#get-suppressions); TypeScript [`suppressions.listAll()`](https://openemail.uk/docs/sdk/reference/suppressions#listAll); Python [`suppressions.list_all()`](https://openemail.uk/docs/python/reference/suppressions#listAll); Ruby [`suppressions.list_all`](https://openemail.uk/docs/ruby/reference/suppressions#listAll); PHP [`suppressions->listAll`](https://openemail.uk/docs/php/reference/suppressions#listAll); Go [`Suppressions.ListAll`](https://openemail.uk/docs/go/reference/suppressions#listAll); C# [`Suppressions.ListAllAsync`](https://openemail.uk/docs/csharp/reference/suppressions#listAll). ### `suppressions().iterate` Stream the suppression list one address at a time ```java PagedIterable iterate(RequestOptions options) ``` Returns a `PagedIterable` that yields one suppressed address at a time, newest first, and requests the next page only once the current one is drained. Nothing is fetched until you consume it, and breaking out of the loop stops the requests. Scopes: `settings:read`. **Parameters** - `options.q` (`String`): Searches the address, the reason and the detail. Words match loosely, and a close spelling is tried when nothing matches exactly. - `options.reason` (`String`): Keeps one kind: `bounce`, `complaint` or `manual`, as in `uk.openemail.constants.SuppressionReasons`. - `options.limit` (`int`): Page size for each request, from 1 to 100. The server defaults to 25. - `options.cursor` (`String`): Starts the walk after this cursor instead of the first page. - `options.apiKey` (`String`): Overrides the client API key for every page of this walk. **Returns** A `PagedIterable` that yields one suppressed address per step. **Example** ```java for (Map row : client.suppressions().iterate(RequestOptions.of("q", "example.com"))) { System.out.println(row.get("email") + " " + row.get("reason")); } ``` **Notes** - The generator is lazy, so an abandoned loop costs only the pages you consumed. Also available in: API [`GET /suppressions`](https://openemail.uk/docs/api/reference/suppressions#get-suppressions); TypeScript [`suppressions.iterate()`](https://openemail.uk/docs/sdk/reference/suppressions#iterate); Python [`suppressions.iterate()`](https://openemail.uk/docs/python/reference/suppressions#iterate); Ruby [`suppressions.iterate`](https://openemail.uk/docs/ruby/reference/suppressions#iterate); PHP [`suppressions->iterate`](https://openemail.uk/docs/php/reference/suppressions#iterate); Go [`Suppressions.Iterate`](https://openemail.uk/docs/go/reference/suppressions#iterate); C# [`Suppressions.IterateAsync`](https://openemail.uk/docs/csharp/reference/suppressions#iterate). ### `suppressions().get` Read one suppressed address by id ```java Map get(String id, RequestOptions options) ``` Returns one row of the suppression list: the address, why it is there, the detail the bounce or complaint carried, whether it can be removed and when it was added. Scopes: `settings:read`. **Parameters** - `id` (`String`, required): The id from `list`. - `options.apiKey` (`String`): Overrides the client API key for this call only. **Returns** A map with `id`, `email`, `reason`, `detail`, `removable` and `createdAt`. **Example** ```java Map row = client.suppressions().get("7b1e2c3d-4f5a-4b6c-8d7e-9f0a1b2c3d4e"); System.out.println(row.get("email") + " " + row.get("removable")); ``` **Notes** - An id that is not on this workspace is a 404 `resource_not_found`. Also available in: API [`GET /suppressions/{id}`](https://openemail.uk/docs/api/reference/suppressions#get-suppressions-id); TypeScript [`suppressions.get()`](https://openemail.uk/docs/sdk/reference/suppressions#get); Python [`suppressions.get()`](https://openemail.uk/docs/python/reference/suppressions#get); Ruby [`suppressions.get`](https://openemail.uk/docs/ruby/reference/suppressions#get); PHP [`suppressions->get`](https://openemail.uk/docs/php/reference/suppressions#get); Go [`Suppressions.Get`](https://openemail.uk/docs/go/reference/suppressions#get); C# [`Suppressions.GetAsync`](https://openemail.uk/docs/csharp/reference/suppressions#get); CLI [`openemail suppressions get`](https://openemail.uk/docs/cli/reference/suppressions#suppressions-get). ### `suppressions().add` Stop sending to an address ```java Map add(Map body, RequestOptions options) ``` Puts an address on the suppression list by hand, with `reason` set to `manual`, so no address in the workspace sends to it again until it is removed. It is the Block an address control on the Blocked addresses screen. Adding an address that is already there changes nothing: the server answers 200 with the row it already holds, whatever its reason, where a new entry answers 201. Either way you get the row back. A new entry fires `suppression.added` to the webhooks that asked for it. Scopes: `settings:write`. **Parameters** - `body.email` (`String`, required): The address to stop sending to. It is trimmed and lower cased. - `options.apiKey` (`String`): Overrides the client API key for this call only. **Returns** A map for the address, new or already there, with the fields `get` returns. **Example** ```java Map row = client.suppressions().add(Body.of("email", "noreply@example.com")); System.out.println(row.get("reason") + " " + row.get("createdAt")); ``` **Notes** - Safe to repeat: a second add finds the first entry, so the SDK retries it after a network failure. - A key limited to particular addresses or domains is refused with 422 `capability_unsupported`, because the list stops mail from every address in the workspace. So is an app connected by anybody but the owner. Also available in: API [`POST /suppressions`](https://openemail.uk/docs/api/reference/suppressions#post-suppressions); TypeScript [`suppressions.add()`](https://openemail.uk/docs/sdk/reference/suppressions#add); Python [`suppressions.add()`](https://openemail.uk/docs/python/reference/suppressions#add); Ruby [`suppressions.add`](https://openemail.uk/docs/ruby/reference/suppressions#add); PHP [`suppressions->add`](https://openemail.uk/docs/php/reference/suppressions#add); Go [`Suppressions.Add`](https://openemail.uk/docs/go/reference/suppressions#add); C# [`Suppressions.AddAsync`](https://openemail.uk/docs/csharp/reference/suppressions#add); CLI [`openemail suppressions add`](https://openemail.uk/docs/cli/reference/suppressions#suppressions-add). ### `suppressions().remove` Allow mail to an address again ```java Map remove(String id, RequestOptions options) ``` Takes an address off the suppression list, so mail may go to it again. It is Allow again on the Blocked addresses screen, and it fires `suppression.removed`. Only a complaint or a manual entry can be removed. A hard bounce answers 409 `suppression_not_removable` and stays, because the address could not take mail: check it is spelled right and send to the corrected one instead. Scopes: `settings:write`. **Parameters** - `id` (`String`, required): The id from `list`. - `options.apiKey` (`String`): Overrides the client API key for this call only. **Returns** A map with `object` set to `suppression`, the `id`, the `email`, and `deleted` set to true. **Example** ```java Page page = client.suppressions().list(RequestOptions.of("q", "ada@example.com")); for (Map row : page) { Map removed = client.suppressions().remove((String) row.get("id")); System.out.println(removed.get("id")); } ``` **Notes** - The SDK does not retry a delete. A 404 on your own second attempt after a lost response means the first one worked. - A key limited to particular addresses or domains is refused with 422 `capability_unsupported`. Also available in: API [`DELETE /suppressions/{id}`](https://openemail.uk/docs/api/reference/suppressions#delete-suppressions-id); TypeScript [`suppressions.remove()`](https://openemail.uk/docs/sdk/reference/suppressions#remove); Python [`suppressions.remove()`](https://openemail.uk/docs/python/reference/suppressions#remove); Ruby [`suppressions.remove`](https://openemail.uk/docs/ruby/reference/suppressions#remove); PHP [`suppressions->remove`](https://openemail.uk/docs/php/reference/suppressions#remove); Go [`Suppressions.Remove`](https://openemail.uk/docs/go/reference/suppressions#remove); C# [`Suppressions.RemoveAsync`](https://openemail.uk/docs/csharp/reference/suppressions#remove); CLI [`openemail suppressions remove`](https://openemail.uk/docs/cli/reference/suppressions#suppressions-remove).