---
title: Blocklist Endpoint
description: Manage your account's blocklist of domains to customize email validation behavior.
---

The blocklist endpoints allow you to manage a custom list of domains that should be treated as blocked for your account. This feature requires a Pro account.

## List Blocklisted Domains

Get a paginated list of all domains in your account's blocklist for the current environment.

### Endpoint

```
GET /blocklist
```

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `per_page` | integer | No | Number of results per page (min: 1, max: 100, default: 25) |

### Request Example

```bash
curl -X GET "https://api.usercheck.com/blocklist" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Success Response (200)

```json
{
  "data": [
    {
      "domain": "example.com",
      "created_at": "2025-01-27T23:32:12+00:00"
    }
  ],
  "links": {
    "first": "https://api.usercheck.com/blocklist?page=1",
    "last": "https://api.usercheck.com/blocklist?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": null,
        "label": "« Previous",
        "active": false
      },
      {
        "url": "https://api.usercheck.com/blocklist?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": null,
        "label": "Next »",
        "active": false
      }
    ],
    "path": "https://api.usercheck.com/blocklist",
    "per_page": 25,
    "to": 1,
    "total": 1
  }
}
```

## Add Domain to Blocklist

Add a new domain to your account's blocklist.

### Endpoint

```
POST /blocklist
```

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `domain` | string | Yes | The domain to add to the blocklist (e.g., example.com) |

### Request Example

```bash
curl -X POST "https://api.usercheck.com/blocklist" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'
```

### Success Response (200)

```json
{
  "domain": "example.com",
  "created_at": "2024-01-28T12:00:00+00:00"
}
```

### Error Response (422) - Domain Already Blocklisted

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "domain": ["The domain has already been blocklisted for this environment."]
  }
}
```

## Bulk Add Domains to Blocklist

Add multiple domains to your account's blocklist in a single request.

### Endpoint

```
POST /blocklist/bulk
```

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `domains` | array | Yes | Array of domains to add (max 1,000 domains) |

### Request Example

```bash
curl -X POST "https://api.usercheck.com/blocklist/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": [
      "example1.com",
      "example2.com",
      "example3.com"
    ]
  }'
```

### Success Response (200)

```json
{
  "succeeded": 2,
  "failed": 1,
  "success": [
    {
      "domain": "example1.com",
      "created_at": "2024-01-28T12:00:00+00:00"
    },
    {
      "domain": "example2.com",
      "created_at": "2024-01-28T12:00:00+00:00"
    }
  ],
  "errors": [
    {
      "domain": "example3.com",
      "error": "The domain has already been blocklisted for this environment."
    }
  ]
}
```

### Validation Rules

- Maximum 1,000 domains per request
- Duplicate domains in the same request are automatically deduplicated
- Each domain must be a valid domain format

## Check if Domain is Blocklisted

Check if a specific domain exists in your account's blocklist for the current environment.

### Endpoint

```
GET /blocklist/{domain}
```

### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `domain` | string | Yes | The domain to check (e.g., example.com) |

### Request Example

```bash
curl -X GET "https://api.usercheck.com/blocklist/example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Success Response (200)

```json
{
  "domain": "example.com",
  "created_at": "2024-01-28T12:00:00+00:00"
}
```

## Remove Domain from Blocklist

Remove a domain from your account's blocklist for the current environment.

### Endpoint

```
DELETE /blocklist/{domain}
```

### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `domain` | string | Yes | The domain to remove (e.g., example.com) |

### Request Example

```bash
curl -X DELETE "https://api.usercheck.com/blocklist/example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Success Response (200)

```json
{
  "message": "Domain removed from blocklist successfully"
}
```

## Error Responses

### Unauthorized (401)

```json
{
  "message": "Unauthorized"
}
```

### Pro Account Required (403)

```json
{
  "message": "This feature requires a Pro account"
}
```

### Domain Not Found (404)

```json
{
  "message": "Domain not found in blocklist"
}
```

### Validation Failed (422)

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "domain": ["The domain is invalid."]
  }
}
```

For bulk operations:

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "domains": ["The domains field is required."]
  }
}
```

## Environment Handling

The blocklist is environment-specific. Domains blocklisted in your test environment will not affect your production environment and vice versa. The environment is determined by the API key used in the request.