Allow and block lists

Allow and block lists decide the result for the specific people, addresses, networks and devices you name. An entry applies to one benefit or to every benefit in the workspace, from the moment it's saved until it expires or you remove it. Every evaluation checks every active entry. See Allow and block lists for how entries shape results.

Examples on this page use a server client:

import { AbuseZero } from "abusezero/server";

const abusezero = new AbuseZero({ key: process.env.ABUSEZERO_SECRET_KEY!, outage: "throw" });

The access list entry objectCopy Anchor Link

{
  "object": "access_list_entry",
  "id": "lst_4c2e8a1f-7b3d-4e9a-8f12-6d0b5a3c9e71",
  "kind": "block",
  "type": "domain",
  "benefit": null,
  "reason": "Reseller domain confirmed by our support team",
  "expires_at": "2027-01-27T09:14:22.000Z",
  "created_at": "2026-10-29T09:14:22.000Z"
}

Reads never return the listed value itself. Keep your own record of what you listed and why, and use the entry ID to manage it.

Entry typesCopy Anchor Link

Add an entryCopy Anchor Link

Adds one value, or up to 50 values in a single call, to an allow or block list.

Also available as abusezero access-lists add in the AbuseZero CLI, abusezero_add_access_list_entry on the AbuseZero MCP server and addAccessListEntry() or addAccessListEntries() in the AbuseZero Node.js SDK.

Request bodyCopy Anchor Link

Omit both expires_at and expires_in_days for an entry that never expires.

Example: one valueCopy Anchor Link

const entry = await abusezero.addAccessListEntry(
  {
    kind: "block",
    type: "domain",
    value: "example.com",
    reason: "Reseller domain confirmed by our support team",
    expires_in_days: 90,
  },
  "block-example-com-2026-10-29",
);

Response: one valueCopy Anchor Link

Returns 201.

{
  "object": "access_list_entry",
  "id": "lst_4c2e8a1f-7b3d-4e9a-8f12-6d0b5a3c9e71"
}

If an active entry with the same kind, type, value and benefit already exists, the response returns that entry's ID instead of creating a second one.

Example: several valuesCopy Anchor Link

const results = await abusezero.addAccessListEntries(
  {
    kind: "allow",
    type: "email_exact",
    values: ["jordan@example.com", "sam@example.com", "not-an-email"],
    reason: "Design partners approved for a second trial",
  },
  "allow-design-partners-2026-10-29",
);

Response: several valuesCopy Anchor Link

Returns 201. Every submitted value gets its own result, in the order you sent them. Valid values are saved even when others in the same call are invalid. Repeated values get one result, and blank values are ignored. A retry with the same Idempotency-Key and body returns these same results, so values the first call saved still read created.

{
  "object": "list",
  "data": [
    {
      "object": "access_list_result",
      "value": "jordan@example.com",
      "status": "created",
      "id": "lst_9a1d3f5e-2c4b-4d8e-a6f7-0b3e5c7d9a12"
    },
    {
      "object": "access_list_result",
      "value": "sam@example.com",
      "status": "already_listed",
      "id": "lst_1e7b9c3d-5f2a-4a6e-8d0c-4b2f6a8e0c34"
    },
    {
      "object": "access_list_result",
      "value": "not-an-email",
      "status": "invalid",
      "reason": "Use an email such as name@example.com. Quoted and international local parts are not supported."
    }
  ]
}

ErrorsCopy Anchor Link

In a call with values, the value problems appear as invalid results instead of errors. For every other code, see REST API errors.

List entriesCopy Anchor Link

Returns entries newest first.

Also available as abusezero access-lists list in the AbuseZero CLI, abusezero_list_access_lists on the AbuseZero MCP server and accessLists() in the AbuseZero Node.js SDK.

Query parametersCopy Anchor Link

ExampleCopy Anchor Link

const page = await abusezero.accessLists({ limit: 100 });

ResponseCopy Anchor Link

Returns 200.

{
  "object": "list",
  "data": [
    {
      "object": "access_list_entry",
      "id": "lst_4c2e8a1f-7b3d-4e9a-8f12-6d0b5a3c9e71",
      "kind": "block",
      "type": "domain",
      "benefit": null,
      "reason": "Reseller domain confirmed by our support team",
      "expires_at": "2027-01-27T09:14:22.000Z",
      "created_at": "2026-10-29T09:14:22.000Z"
    }
  ],
  "next_cursor": null
}

When next_cursor is a string, pass it as cursor to read the next page. See Pagination in the AbuseZero REST API overview.

Retrieve an entryCopy Anchor Link

Also available as abusezero access-lists get in the AbuseZero CLI, abusezero_get_access_list_entry on the AbuseZero MCP server and call() in the AbuseZero Node.js SDK.

Path parametersCopy Anchor Link

ExampleCopy Anchor Link

const entry = await abusezero.call("/v1/access-lists/lst_4c2e8a1f-7b3d-4e9a-8f12-6d0b5a3c9e71");

ResponseCopy Anchor Link

Returns 200 with an access list entry object.

ErrorsCopy Anchor Link

Remove an entryCopy Anchor Link

Removes an entry. It stops applying to evaluations immediately.

Also available as abusezero access-lists delete in the AbuseZero CLI, abusezero_delete_access_list_entry on the AbuseZero MCP server and deleteAccessListEntry() in the AbuseZero Node.js SDK.

Path parametersCopy Anchor Link

ExampleCopy Anchor Link

await abusezero.deleteAccessListEntry(
  "lst_4c2e8a1f-7b3d-4e9a-8f12-6d0b5a3c9e71",
  "remove-lst-4c2e8a1f",
);

ResponseCopy Anchor Link

Returns 200. Removing an entry that's already gone also succeeds.

{
  "object": "deleted",
  "id": "lst_4c2e8a1f-7b3d-4e9a-8f12-6d0b5a3c9e71",
  "deleted": true
}

RelatedCopy Anchor Link