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:

ParameterTypeRequiredDescription

team_idstringNoFilter by team ID
campaign_idstringNoFilter by campaign ID
levelstringNoFilter by level: organization, team, or campaign
typestringNoFilter by type: email, domain, or linkedin
searchstringNoSearch in item field
sort_bystringNoSort field: created_at, item, or type (default: created_at)
sort_orderstringNoSort direction: asc or desc (default: desc)
limitnumberNoResults per page (default: 50, max: 100)
offsetnumberNoPagination 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:

ParameterTypeRequiredDescription

itemstringYesEmail address, domain, or LinkedIn URL (max: 500 chars)
levelstringYesScope level: organization, team, or campaign
team_idstringNoTeam ID (required if level is team)
campaign_idstringNoCampaign 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:

LevelDescriptionRequired Parameters

organizationApplies to entire organizationNone
teamApplies to a specific teamteam_id
campaignApplies to a specific campaigncampaign_id

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

Blacklist Types

TypeDescriptionExampleAuto-Detected

emailSpecific email addressjohn@example.comYes (if contains @)
domainEntire domainexample.comYes (if no @ and not LinkedIn URL)
linkedinLinkedIn profile URLlinkedin.com/in/johndoeYes (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"
  }'