> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fraudiant.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Blocklist Management

> Manage your custom domain blocklist to enforce organization-specific email policies (Pro feature).

<Info>
  **Pro Feature**: The blocklist functionality requires a Pro account. [Upgrade now](https://app.fraudiant.com/upgrade) to unlock this feature.
</Info>

## Overview

The blocklist feature allows you to maintain a custom list of domains that should be blocked in your application. This is useful for:

* Enforcing company-specific email policies
* Blocking competitors or specific organizations
* Maintaining a custom deny list beyond disposable email detection
* Implementing organization-specific compliance rules

<Warning>
  **Environment-Specific**: Blocklists are environment-specific. Domains blocklisted in your test environment will not affect your production environment and vice versa.
</Warning>

***

## List Blocklisted Domains

```
GET /blocklist
```

Retrieves a paginated list of all domains in your blocklist.

### Query Parameters

<ParamField query="per_page" type="integer" default="25">
  Number of results per page (1-100)
</ParamField>

### Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.fraudiant.com/blocklist?per_page=50" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.fraudiant.com/blocklist?per_page=50', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  headers = {'Authorization': 'Bearer YOUR_API_KEY'}
  response = requests.get(
      'https://api.fraudiant.com/blocklist',
      params={'per_page': 50},
      headers=headers
  )

  data = response.json()
  ```
</CodeGroup>

### Response Example

```json theme={null}
{
  "status": 200,
  "data": [
    {
      "domain": "example.com",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "domain": "competitor.com",
      "created_at": "2024-01-16T14:22:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 50,
    "total": 2
  }
}
```

***

## Add Single Domain

```
POST /blocklist
```

Adds a single domain to your blocklist.

### Request Body

<ParamField body="domain" type="string" required>
  The domain to add to the blocklist (e.g., `example.com`)
</ParamField>

### Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.fraudiant.com/blocklist" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"domain": "example.com"}'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.fraudiant.com/blocklist', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      domain: 'example.com'
    })
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  headers = {'Authorization': 'Bearer YOUR_API_KEY'}
  payload = {'domain': 'example.com'}

  response = requests.post(
      'https://api.fraudiant.com/blocklist',
      json=payload,
      headers=headers
  )

  data = response.json()
  ```
</CodeGroup>

### Response Example

```json theme={null}
{
  "status": 201,
  "domain": "example.com",
  "created_at": "2024-01-15T10:30:00Z"
}
```

### Error Responses

**Domain Already Blocklisted (422)**

```json theme={null}
{
  "status": 422,
  "error": "Domain is already in your blocklist"
}
```

***

## Add Multiple Domains (Bulk)

```
POST /blocklist/bulk
```

Adds up to 1,000 domains to your blocklist in a single request. Automatically handles duplicates.

### Request Body

<ParamField body="domains" type="array" required>
  Array of domain strings to add (maximum 1,000 domains per request)
</ParamField>

### Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.fraudiant.com/blocklist/bulk" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "domains": ["example1.com", "example2.com", "example3.com"]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.fraudiant.com/blocklist/bulk', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      domains: ['example1.com', 'example2.com', 'example3.com']
    })
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  headers = {'Authorization': 'Bearer YOUR_API_KEY'}
  payload = {
      'domains': ['example1.com', 'example2.com', 'example3.com']
  }

  response = requests.post(
      'https://api.fraudiant.com/blocklist/bulk',
      json=payload,
      headers=headers
  )

  data = response.json()
  ```
</CodeGroup>

### Response Example

```json theme={null}
{
  "status": 200,
  "succeeded": 2,
  "failed": 1,
  "results": [
    {
      "domain": "example1.com",
      "status": "success",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "domain": "example2.com",
      "status": "success",
      "created_at": "2024-01-15T10:30:01Z"
    },
    {
      "domain": "example3.com",
      "status": "failed",
      "error": "Domain is already in your blocklist"
    }
  ]
}
```

<Info>
  Bulk operations automatically deduplicate entries. If a domain is already in your blocklist, it will be marked as failed but won't cause the entire request to fail.
</Info>

***

## Check Domain Status

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

Checks if a specific domain is in your blocklist.

### Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.fraudiant.com/blocklist/example.com" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.fraudiant.com/blocklist/example.com', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const data = await response.json();
  ```
</CodeGroup>

### Response Example

```json theme={null}
{
  "status": 200,
  "domain": "example.com",
  "created_at": "2024-01-15T10:30:00Z",
  "blocklisted": true
}
```

### Error Response (Not Found)

```json theme={null}
{
  "status": 404,
  "error": "Domain not found in blocklist"
}
```

***

## Remove Domain

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

Removes a domain from your blocklist.

### Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.fraudiant.com/blocklist/example.com" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.fraudiant.com/blocklist/example.com', {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  headers = {'Authorization': 'Bearer YOUR_API_KEY'}
  response = requests.delete(
      'https://api.fraudiant.com/blocklist/example.com',
      headers=headers
  )

  data = response.json()
  ```
</CodeGroup>

### Response Example

```json theme={null}
{
  "status": 200,
  "message": "Domain removed from blocklist successfully"
}
```

***

## Common Error Responses

### Unauthorized (401)

```json theme={null}
{
  "status": 401,
  "error": "Unauthorized. Please provide a valid API key."
}
```

### Pro Feature Required (403)

```json theme={null}
{
  "status": 403,
  "error": "This feature requires a Pro account."
}
```

<Card title="Upgrade to Pro" icon="crown" href="https://app.fraudiant.com/upgrade">
  Unlock blocklist management and other Pro features
</Card>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Test in development first">
    Always test blocklist changes in your development environment before applying them to production to avoid accidentally blocking legitimate users.
  </Accordion>

  <Accordion title="Use bulk operations for efficiency">
    When adding multiple domains, use the bulk endpoint to reduce API calls and improve performance.
  </Accordion>

  <Accordion title="Document blocklist decisions">
    Keep an internal record of why domains are blocklisted to help with future audits and policy reviews.
  </Accordion>

  <Accordion title="Regularly review your blocklist">
    Periodically audit your blocklist to remove outdated entries and ensure it aligns with current policies.
  </Accordion>

  <Accordion title="Combine with disposable detection">
    Use blocklists in addition to disposable email detection for comprehensive fraud prevention.
  </Accordion>
</AccordionGroup>

***

## Integration Example

```javascript theme={null}
async function validateEmail(email) {
  const domain = email.split('@')[1];

  // First, check if domain is blocklisted
  const blocklistCheck = await fetch(
    `https://api.fraudiant.com/blocklist/${domain}`,
    {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    }
  );

  if (blocklistCheck.status === 200) {
    return { allowed: false, reason: 'Domain is blocklisted' };
  }

  // Then validate the full email
  const emailCheck = await fetch(
    `https://api.fraudiant.com/email/${email}`,
    {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    }
  );

  const data = await emailCheck.json();

  if (data.disposable || data.spam) {
    return { allowed: false, reason: 'Disposable or spam email' };
  }

  return { allowed: true };
}
```