# Add block list entries

> Block companies or mailboxes from outreach. Idempotent, up to 500 per call.

Canonical: https://revnu.com/docs/blocklist-add

```bash
curl -X POST -H "Authorization: Bearer $REVNU_API_TOKEN" \
  -H "content-type: application/json" \
  -d '{"values":["acme.com","Sarah Lee <sarah@globex.com>"],"reason":"existing customer"}' \
  https://revnu.com/api/v1/blocklist
```

## Body

`values`, 1 to 500 raw strings of up to 320 characters each: bare domains, emails, `mailto:` links or `Name <email>` forms, all normalised. `reason` is an optional note of up to 500 characters stored on every entry in the call.

## Response

`{ "added": 2, "existing": 0, "invalid": [] }`. `existing` counts values already on the list, so re-sending a whole list is safe. `invalid` lists the strings that could not be read as a domain or an email, trimmed and cut to 200 characters, blanks dropped; nothing else in the call is affected by them. Entries carry `source: "api"` and the token's label.

## Frequently asked questions

### When does a new entry take effect?

On the next send or research decision. Anything already delivered is not recalled.

### Which scope does this need?

`leads:write`. A token without it gets `403` with `requiredScope` in the body. `GET /me` shows a token's scopes.

### Are responses cached?

No. Every response is `Cache-Control: no-store`, so what you read is current.