Blacklist API

Manage email and domain blacklists

The blacklist API allows you to manage email addresses and domains that should be excluded from your outreach. Blacklisted items will never receive emails from your campaigns.

ℹ️

V2 API

Blacklist management is available in V2 API.

List Blacklist Items

Get all blacklisted emails and domains.

V2 API

bash

curl -X GET 'https://api.supersend.io/v2/blacklist?team_id=xxx&campaign_id=yyy&level=team&type=email&search=competitor&sort_by=created_at&sort_order=desc&limit=50' \ -H "Authorization: Bearer YOUR_API_KEY"

# Response (200 OK) { "success": true, "data": [ { "object": "blacklist_item", "id": "blacklist-uuid", "item": "competitor@example.com", "type": "email", "level": "team", "team_wide": true, "team": { "id": "team-uuid", "name": "Sales Team" }, "campaign": null, "created_by": { "id": "user-uuid", "name": "John Doe", "email": "john@example.com" }, "created_at": "2025-01-01T00:00:00Z", "updated_at": "2025-01-01T00:00:00Z" }, { "object": "blacklist_item", "id": "blacklist-uuid-2", "item": "donotcontact.com", "type": "domain", "level": "organization", "team_wide": true, "team": null, "campaign": null, "created_by": null, "created_at": "2025-01-01T00:00:00Z", "updated_at": "2025-01-01T00:00:00Z" } ], "pagination": { "total": 25, "limit": 50, "offset": 0, "has_more": false }, "request_id": "req_a1b2c3d4e5f6789012345678" }

V2 Query Parameters:

Parameter	Type	Required	Description
`team_id`	string	No	Filter by team ID
`campaign_id`	string	No	Filter by campaign ID
`level`	string	No	Filter by level: `organization`, `team`, or `campaign`
`type`	string	No	Filter by type: `email`, `domain`, or `linkedin`
`search`	string	No	Search in item field
`sort_by`	string	No	Sort field: `created_at`, `item`, or `type` (default: `created_at`)
`sort_order`	string	No	Sort direction: `asc` or `desc` (default: `desc`)
`limit`	number	No	Results per page (default: 50, max: 100)
`offset`	number	No	Pagination offset (default: 0)

Add to Blacklist

Add an email or domain to the blacklist.

V2 API

bash

curl -X POST 'https://api.supersend.io/v2/blacklist' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "item": "competitor@example.com", "level": "team", "team_id": "team-uuid" }'

# Response (201 Created) { "success": true, "data": { "object": "blacklist_item", "id": "blacklist-uuid", "item": "competitor@example.com", "type": "email", "level": "team", "team_id": "team-uuid", "campaign_id": null, "created_at": "2025-01-01T00:00:00Z" }, "metadata": { "is_new": true }, "request_id": "req_a1b2c3d4e5f6789012345678" }

V2 Create Parameters:

Parameter	Type	Required	Description
`item`	string	Yes	Email address, domain, or LinkedIn URL (max: 500 chars)
`level`	string	Yes	Scope level: `organization`, `team`, or `campaign`
`team_id`	string	No	Team ID (required if `level` is `team`)
`campaign_id`	string	No	Campaign ID (required if `level` is `campaign`)

Type Detection:

The API automatically detects the type based on the item format:

- If contains @, type is email
- If matches LinkedIn URL pattern (linkedin.com/in/...), type is linkedin
- Otherwise, type is domain

Domains are automatically cleaned (removes http://, https://, www., etc.)

Note: If a duplicate item already exists at the same level, the API returns 200 OK with metadata.is_new: false instead of creating a duplicate.

Remove from Blacklist

Remove an item from the blacklist.

V2 API

bash

curl -X DELETE 'https://api.supersend.io/v2/blacklist/blacklist-uuid' \ -H "Authorization: Bearer YOUR_API_KEY"

# Response (200 OK) { "success": true, "data": { "id": "blacklist-uuid", "deleted": true }, "request_id": "req_a1b2c3d4e5f6789012345678" }

Blacklist Levels

Blacklist items can be scoped at three levels:

Level	Description	Required Parameters
`organization`	Applies to entire organization	None
`team`	Applies to a specific team	`team_id`
`campaign`	Applies to a specific campaign	`campaign_id`

Note: Campaign-level blacklist items inherit from team-level, and team-level items inherit from organization-level.

Blacklist Types

Type	Description	Example	Auto-Detected
`email`	Specific email address	`john@example.com`	Yes (if contains `@`)
`domain`	Entire domain	`example.com`	Yes (if no `@` and not LinkedIn URL)
`linkedin`	LinkedIn profile URL	`linkedin.com/in/johndoe`	Yes (if matches LinkedIn pattern)

When a domain is blacklisted, all email addresses at that domain are blocked.

Best Practices

1. Blacklist Competitors (Organization-Level)

Prevent accidentally emailing competitor companies across all teams:

bash

curl -X POST 'https://api.supersend.io/v2/blacklist' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "item": "competitor.com",
    "level": "organization"
  }'

2. Honor Unsubscribe Requests (Team-Level)

When someone asks to be removed outside the normal unsubscribe flow:

bash

curl -X POST 'https://api.supersend.io/v2/blacklist' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "item": "user@example.com",
    "level": "team",
    "team_id": "team-uuid"
  }'

3. Protect Key Accounts (Campaign-Level)

Blacklist domains of key customers or partners for a specific campaign:

bash

curl -X POST 'https://api.supersend.io/v2/blacklist' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "item": "bigcustomer.com",
    "level": "campaign",
    "campaign_id": "campaign-uuid"
  }'

4. Blacklist LinkedIn Profiles

Block specific LinkedIn profiles from receiving connection requests:

bash

curl -X POST 'https://api.supersend.io/v2/blacklist' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "item": "linkedin.com/in/johndoe",
    "level": "team",
    "team_id": "team-uuid"
  }'

Bulk Operations

Bulk Import via CSV

Upload a CSV file to add multiple items to the blacklist at once. The import is processed asynchronously in chunks of 1,000 records to handle large files efficiently.

ℹ️

V1 API

Bulk import is available via the V1 API. Large uploads may take several minutes to complete.

bash

curl -X POST 'https://api.supersend.io/api/bulk-blacklist' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "blacklist=@/path/to/blacklist.csv" \
  -F "level=team" \
  -F "TeamId=team-uuid" \
  -F 700 dark:text-green-400">'mapping_fields={"email_column":"item"}'# Response (200 OK)
{
  "message": "Upload received. Processing will begin shortly. Large uploads may take several minutes to complete.",
  "uploadId": "upload-uuid"
}

Parameters:

Parameter	Type	Required	Description
`blacklist`	file	Yes	CSV file containing items to blacklist (max: 1GB)
`level`	string	Yes	Scope level: `organization`, `team`, or `campaign`
`TeamId`	string	Conditional	Team ID (required if `level` is `team`)
`CampaignId`	string	Conditional	Campaign ID (required if `level` is `campaign`)
`mapping_fields`	JSON string	No	Column mapping object (e.g., `{"your_column_name":"item"}`)

CSV Format:

The CSV should have a header row

By default, the first column is used as the blacklist item

Use mapping_fields to specify which column contains the items to blacklist

Items are automatically classified as email, domain, or linkedin based on format

Processing Details:

Files are uploaded to secure cloud storage and processed in the background

Large files (up to 1GB) are streamed from storage rather than loaded into memory, enabling efficient processing of massive imports

Records are processed in batches of 1,000 for optimal performance

Duplicate items (already in your blacklist) are automatically skipped

Duplicates within the CSV file are also deduplicated

Example CSV:

csv

email
competitor@example.com
badactor.com
linkedin.com/in/spammer123

Bulk Delete

Delete multiple blacklist items at once.

ℹ️

V1 API

Bulk delete is available via the V1 API.

bash

# Delete specific items by ID curl -X POST 'https://api.supersend.io/api/blacklist/bulk/' \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "action": "delete", "blacklist_ids": ["blacklist-uuid-1", "blacklist-uuid-2"], "page": "admin" }'

# Response (200 OK) { "success": true, "message": "2 blacklist items deleted successfully", "deletedCount": 2 }

Delete All with Exclusions:

bash

# Delete all items except specified ones (with optional filters)
curl -X POST 'https://api.supersend.io/api/blacklist/bulk/' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "delete",
    "exclude_ids": ["keep-this-uuid"],
    "page": "admin",
    "filters": {
      "searchQuery": "competitor"
    }
  }'

Parameters:

Parameter	Type	Required	Description
`action`	string	Yes	Action to perform: `delete`
`blacklist_ids`	array	Conditional	Array of blacklist item IDs to delete
`exclude_ids`	array	Conditional	Array of IDs to exclude when deleting all (use empty array `[]` to delete all)
`page`	string	Yes	Context: `admin` (organization-level) or `team`
`TeamId`	string	Conditional	Required when `page` is `team`
`filters`	object	No	Optional filters to narrow selection
`filters.searchQuery`	string	No	Search term to filter items
`filters.CampaignId`	string	No	Filter by campaign (team page only)

Note: You must provide either blacklist_ids (to delete specific items) or exclude_ids (to delete all except specified items).