> For the complete documentation index, see [llms.txt](https://run.emailchaser.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://run.emailchaser.com/api-reference/blocklist.md).

# Blocklist

## List blocklist entries

> Returns the suppression entries (blocked domains and email addresses) that apply to the calling key's workspace, newest first. By default that is both lists: the workspace's own entries and the account-wide ones inherited from the main workspace. Narrow with \`scope=workspace\` or \`scope=global\`. Each item reports which list it came from.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.BlocklistListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/models.BlocklistEntry"}},"totalCount":{"type":"integer"}}},"models.BlocklistEntry":{"type":"object","properties":{"createdAt":{"type":"string"},"domain":{"type":"string"},"emailAddress":{"description":"EmailAddress is the blocked address when the entry blocks one address\nrather than a whole domain.","type":"string"},"id":{"type":"integer"},"scope":{"description":"Scope is \"workspace\" for the calling workspace's own entry, \"global\" for\nan account-wide one.","type":"string","enum":["workspace","global"]},"workspaceId":{"description":"WorkspaceId is the workspace the entry is stored on. For a global entry\nread from a sub-workspace this is the main workspace, not the caller.","type":"integer"}}},"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/blocklist":{"get":{"description":"Returns the suppression entries (blocked domains and email addresses) that apply to the calling key's workspace, newest first. By default that is both lists: the workspace's own entries and the account-wide ones inherited from the main workspace. Narrow with `scope=workspace` or `scope=global`. Each item reports which list it came from.","tags":["Blocklist"],"summary":"List blocklist entries","parameters":[{"schema":{"type":"string"},"description":"Bearer <API_KEY>","name":"Authorization","in":"header","required":true},{"schema":{"type":"string","enum":["workspace","global","all"]},"description":"Which list to return: workspace, global, or all (default all)","name":"scope","in":"query"},{"schema":{"type":"string"},"description":"Case-insensitive substring match on the domain or email address","name":"search","in":"query"},{"schema":{"type":"integer"},"description":"Page size (default 100, max 1000)","name":"limit","in":"query"},{"schema":{"type":"integer"},"description":"Offset (default 0)","name":"offset","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.BlocklistListResponse"}}}},"400":{"description":"Invalid scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"500":{"description":"Failed to list entries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}}}}}}
```

## Add blocklist entries

> Adds up to 1000 suppression entries in one call. Each value is either a full email address (contains "@") or a bare domain. Existing entries and invalid values are skipped, so the call is safe to retry and suited to carrying over a suppression list from another sending platform. \`scope\` defaults to "workspace", which suppresses for the calling key's workspace only; "global" suppresses across every workspace on the account and requires a main workspace's key.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.BlocklistAddResponse":{"type":"object","properties":{"created":{"description":"Created is the number of new suppression entries written.","type":"integer"},"scope":{"description":"Scope is the list the entries were written to.","type":"string","enum":["workspace","global"]},"skipped":{"description":"Skipped is the number of values ignored because they already existed or\nfailed validation.","type":"integer"}}},"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}},"models.BlocklistAddRequest":{"type":"object","required":["values"],"properties":{"scope":{"description":"Scope is \"workspace\" (default) or \"global\". A global entry suppresses\nacross every workspace on the account and can only be written with a\nmain workspace's API key.","type":"string","enum":["workspace","global"]},"values":{"description":"Values holds the email addresses and/or domains to block, up to 1000 per\nrequest.","type":"array","items":{"type":"string"}}}}}},"paths":{"/blocklist":{"post":{"description":"Adds up to 1000 suppression entries in one call. Each value is either a full email address (contains \"@\") or a bare domain. Existing entries and invalid values are skipped, so the call is safe to retry and suited to carrying over a suppression list from another sending platform. `scope` defaults to \"workspace\", which suppresses for the calling key's workspace only; \"global\" suppresses across every workspace on the account and requires a main workspace's key.","tags":["Blocklist"],"summary":"Add blocklist entries","parameters":[{"schema":{"type":"string"},"description":"Bearer <API_KEY>","name":"Authorization","in":"header","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.BlocklistAddResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"403":{"description":"Only a main workspace's key may write the account-wide blocklist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"500":{"description":"Failed to add entries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.BlocklistAddRequest"}}},"description":"Values to block","required":true}}}}}
```

## Delete blocklist entries

> Removes up to 1000 entries in one call, by id or by value. Values are matched case-insensitively against both the domain and the email-address column, so unblocking "acme.com" removes the domain entry, not the individual addresses on it. \`scope\` limits the delete to one list and defaults to "workspace"; "all" covers both, and anything touching the account-wide list requires a main workspace's key. Entries that match nothing the caller may delete are counted as skipped rather than failing the call.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.BlocklistDeleteResponse":{"type":"object","properties":{"deleted":{"description":"Deleted is the number of entries removed.","type":"integer"},"skipped":{"description":"Skipped is the number of requested values or ids that matched nothing\nthe caller may delete.","type":"integer"}}},"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}},"models.BlocklistDeleteRequest":{"type":"object","properties":{"ids":{"description":"Ids are entry ids as returned by GET /blocklist.","type":"array","items":{"type":"integer"}},"scope":{"description":"Scope limits the delete to one list: \"workspace\" (default), \"global\", or\n\"all\". Deleting from \"global\" requires a main workspace's key.","type":"string","enum":["workspace","global","all"]},"values":{"description":"Values are domains or email addresses to unblock, matched\ncase-insensitively. Values not present are counted as skipped.","type":"array","items":{"type":"string"}}}}}},"paths":{"/blocklist":{"delete":{"description":"Removes up to 1000 entries in one call, by id or by value. Values are matched case-insensitively against both the domain and the email-address column, so unblocking \"acme.com\" removes the domain entry, not the individual addresses on it. `scope` limits the delete to one list and defaults to \"workspace\"; \"all\" covers both, and anything touching the account-wide list requires a main workspace's key. Entries that match nothing the caller may delete are counted as skipped rather than failing the call.","tags":["Blocklist"],"summary":"Delete blocklist entries","parameters":[{"schema":{"type":"string"},"description":"Bearer <API_KEY>","name":"Authorization","in":"header","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.BlocklistDeleteResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"403":{"description":"Only a main workspace's key may write the account-wide blocklist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"500":{"description":"Failed to delete entries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.BlocklistDeleteRequest"}}},"description":"Entries to remove","required":true}}}}}
```

## Get a blocklist entry

> Returns one suppression entry by id. Entries inherited from the account-wide list are visible here too, and report scope "global".

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.BlocklistEntry":{"type":"object","properties":{"createdAt":{"type":"string"},"domain":{"type":"string"},"emailAddress":{"description":"EmailAddress is the blocked address when the entry blocks one address\nrather than a whole domain.","type":"string"},"id":{"type":"integer"},"scope":{"description":"Scope is \"workspace\" for the calling workspace's own entry, \"global\" for\nan account-wide one.","type":"string","enum":["workspace","global"]},"workspaceId":{"description":"WorkspaceId is the workspace the entry is stored on. For a global entry\nread from a sub-workspace this is the main workspace, not the caller.","type":"integer"}}},"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/blocklist/{id}":{"get":{"description":"Returns one suppression entry by id. Entries inherited from the account-wide list are visible here too, and report scope \"global\".","tags":["Blocklist"],"summary":"Get a blocklist entry","parameters":[{"schema":{"type":"string"},"description":"Bearer <API_KEY>","name":"Authorization","in":"header","required":true},{"schema":{"type":"integer"},"description":"Blocklist entry ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.BlocklistEntry"}}}},"400":{"description":"Invalid id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"404":{"description":"Entry not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"500":{"description":"Failed to load entry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}}}}}}
```

## Update a blocklist entry

> Changes the blocked value, the scope, or both. A value containing "@" is stored as an email address, otherwise as a domain, so an entry can be converted between the two. Moving an entry to or from the account-wide list requires a main workspace's key, and moves the entry onto the main workspace.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.BlocklistEntry":{"type":"object","properties":{"createdAt":{"type":"string"},"domain":{"type":"string"},"emailAddress":{"description":"EmailAddress is the blocked address when the entry blocks one address\nrather than a whole domain.","type":"string"},"id":{"type":"integer"},"scope":{"description":"Scope is \"workspace\" for the calling workspace's own entry, \"global\" for\nan account-wide one.","type":"string","enum":["workspace","global"]},"workspaceId":{"description":"WorkspaceId is the workspace the entry is stored on. For a global entry\nread from a sub-workspace this is the main workspace, not the caller.","type":"integer"}}},"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}},"models.BlocklistUpdateRequest":{"type":"object","properties":{"scope":{"description":"Scope moves the entry between the workspace list and the account-wide\nlist. Moving an entry to \"global\" requires a main workspace's key.","type":"string","enum":["workspace","global"]},"value":{"description":"Value is the new domain or email address. Which of the two the entry\nholds is re-inferred from whether the value contains \"@\", so an entry\ncan be converted between a domain block and an address block.","type":"string"}}}}},"paths":{"/blocklist/{id}":{"put":{"description":"Changes the blocked value, the scope, or both. A value containing \"@\" is stored as an email address, otherwise as a domain, so an entry can be converted between the two. Moving an entry to or from the account-wide list requires a main workspace's key, and moves the entry onto the main workspace.","tags":["Blocklist"],"summary":"Update a blocklist entry","parameters":[{"schema":{"type":"string"},"description":"Bearer <API_KEY>","name":"Authorization","in":"header","required":true},{"schema":{"type":"integer"},"description":"Blocklist entry ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.BlocklistEntry"}}}},"400":{"description":"Invalid request body or id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"403":{"description":"Only a main workspace's key may write the account-wide blocklist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"404":{"description":"Entry not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"409":{"description":"That value is already blocked in the target list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"500":{"description":"Failed to update entry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.BlocklistUpdateRequest"}}},"description":"Fields to change","required":true}}}}}
```

## Delete a blocklist entry

> Removes one suppression entry, unblocking the domain or address. A sub-workspace key cannot delete an account-wide entry it merely inherits.

```json
{"openapi":"3.1.1","info":{"title":"Emailchaser API","version":"1.0"},"servers":[{"url":"https://api.emailchaser.com/r"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"models.BlocklistDeleteEntryResponse":{"type":"object","properties":{"id":{"type":"integer"},"message":{"type":"string"}}},"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"models.ErrorUnauthorized":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/blocklist/{id}":{"delete":{"description":"Removes one suppression entry, unblocking the domain or address. A sub-workspace key cannot delete an account-wide entry it merely inherits.","tags":["Blocklist"],"summary":"Delete a blocklist entry","parameters":[{"schema":{"type":"string"},"description":"Bearer <API_KEY>","name":"Authorization","in":"header","required":true},{"schema":{"type":"integer"},"description":"Blocklist entry ID","name":"id","in":"path","required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.BlocklistDeleteEntryResponse"}}}},"400":{"description":"Invalid id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorUnauthorized"}}}},"403":{"description":"Only a main workspace's key may write the account-wide blocklist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"404":{"description":"Entry not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"500":{"description":"Failed to delete entry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}}}}}}
```