Blocklist Management

Pro Feature: The blocklist functionality requires a Pro account. Upgrade now to unlock this feature.

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

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

List Blocklisted Domains

GET /blocklist

Retrieves a paginated list of all domains in your blocklist.

Query Parameters

integer

default:"25"

Number of results per page (1-100)

Request Example

curl -X GET "https://api.fraudiant.com/blocklist?per_page=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

const data = await response.json();

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()

Response Example

{
  "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

string

required

The domain to add to the blocklist (e.g., example.com)

Request Example

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

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();

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()

Response Example

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

Error Responses

Domain Already Blocklisted (422)

{
  "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

array

required

Array of domain strings to add (maximum 1,000 domains per request)

Request Example

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"]
  }'

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();

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()

Response Example

{
  "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"
    }
  ]
}

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.

Check Domain Status

GET /blocklist/{domain}

Checks if a specific domain is in your blocklist.

Request Example

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

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

const data = await response.json();

Response Example

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

Error Response (Not Found)

{
  "status": 404,
  "error": "Domain not found in blocklist"
}

Remove Domain

DELETE /blocklist/{domain}

Removes a domain from your blocklist.

Request Example

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

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

const data = await response.json();

import requests

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

data = response.json()

Response Example

{
  "status": 200,
  "message": "Domain removed from blocklist successfully"
}

Common Error Responses

Unauthorized (401)

{
  "status": 401,
  "error": "Unauthorized. Please provide a valid API key."
}

Pro Feature Required (403)

{
  "status": 403,
  "error": "This feature requires a Pro account."
}

Upgrade to Pro

Unlock blocklist management and other Pro features

Best Practices

Test in development first

Always test blocklist changes in your development environment before applying them to production to avoid accidentally blocking legitimate users.

Use bulk operations for efficiency

When adding multiple domains, use the bulk endpoint to reduce API calls and improve performance.

Document blocklist decisions

Keep an internal record of why domains are blocklisted to help with future audits and policy reviews.

Regularly review your blocklist

Periodically audit your blocklist to remove outdated entries and ensure it aligns with current policies.

Combine with disposable detection

Use blocklists in addition to disposable email detection for comprehensive fraud prevention.

Integration Example

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 };
}

Introduction

Endpoints

Blocklist Management

Overview

List Blocklisted Domains

Query Parameters

Request Example

Response Example

Add Single Domain

Request Body

Request Example

Response Example

Error Responses

Add Multiple Domains (Bulk)

Request Body

Request Example

Response Example

Check Domain Status

Request Example

Response Example

Error Response (Not Found)

Remove Domain

Request Example

Response Example

Common Error Responses

Unauthorized (401)

Pro Feature Required (403)

Upgrade to Pro

Best Practices

Integration Example

​Overview

​List Blocklisted Domains

​Query Parameters

​Request Example

​Response Example

​Add Single Domain

​Request Body

​Request Example

​Response Example

​Error Responses

​Add Multiple Domains (Bulk)

​Request Body

​Request Example

​Response Example

​Check Domain Status

​Request Example

​Response Example

​Error Response (Not Found)

​Remove Domain

​Request Example

​Response Example

​Common Error Responses

​Unauthorized (401)

​Pro Feature Required (403)

Upgrade to Pro

​Best Practices

​Integration Example

Overview

List Blocklisted Domains

Query Parameters

Request Example

Response Example

Add Single Domain

Request Body

Request Example

Response Example

Error Responses

Add Multiple Domains (Bulk)

Request Body

Request Example

Response Example

Check Domain Status

Request Example

Response Example

Error Response (Not Found)

Remove Domain

Request Example

Response Example

Common Error Responses

Unauthorized (401)

Pro Feature Required (403)

Best Practices

Integration Example