Suppression List Management

Administrative endpoints for managing the global suppression list. Suppressed emails are blocked from receiving emails to protect sender reputation and comply with unsubscribe requests.

Overview

The suppression list contains email addresses that should not receive emails from any workspace on the platform. Emails can be suppressed for various reasons including bounces, complaints, unsubscribes, or manual admin actions.

Base URL

/api/admin/email/suppression

Suppression Reasons

Reason	Description
`bounce`	Email address hard bounced
`complaint`	Recipient marked email as spam
`unsubscribe`	User unsubscribed from emails
`manual`	Manually added by admin
`invalid`	Invalid email format or domain

Endpoints

List Suppressed Emails

Retrieve all suppressed email addresses with pagination and filtering.

GET /api/admin/email/suppression

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`limit`	integer	No	Items per page (default: 20, max: 100)
`reason`	string	No	Filter by suppression reason
`workspaceId`	string	No	Filter by originating workspace
`email`	string	No	Search by email address (partial match)
`dateFrom`	string	No	Filter from date (ISO 8601)
`dateTo`	string	No	Filter to date (ISO 8601)
`sortBy`	string	No	Sort field: `createdAt`, `email`
`sortOrder`	string	No	Sort direction: `asc` or `desc`

Request Example

curl -X GET "https://api.yourdomain.com/api/admin/email/suppression?reason=bounce&limit=50" \
  -H "Authorization: Bearer <admin_token>"

Response Example

{
  "success": true,
  "data": [
    {
      "id": "sup_12345",
      "email": "bounced@example.com",
      "reason": "bounce",
      "source": "automatic",
      "workspaceId": "ws_abc123",
      "workspaceName": "Acme Corp",
      "metadata": {
        "bounceType": "Permanent",
        "bounceSubType": "General",
        "diagnosticCode": "550 5.1.1 User unknown"
      },
      "createdAt": "2024-02-01T14:30:00Z",
      "expiresAt": null
    },
    {
      "id": "sup_12346",
      "email": "unsubscribed@example.com",
      "reason": "unsubscribe",
      "source": "user_action",
      "workspaceId": "ws_def456",
      "workspaceName": "TechStart Inc",
      "metadata": {
        "unsubscribeSource": "footer_link",
        "ipAddress": "192.168.1.1"
      },
      "createdAt": "2024-01-20T09:15:00Z",
      "expiresAt": null
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 1250,
    "totalPages": 25
  }
}

Get Suppressed Email Details

Retrieve details for a specific suppressed email.

GET /api/admin/email/suppression/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Suppression entry ID

Request Example

curl -X GET "https://api.yourdomain.com/api/admin/email/suppression/sup_12345" \
  -H "Authorization: Bearer <admin_token>"

Response Example

{
  "success": true,
  "data": {
    "id": "sup_12345",
    "email": "bounced@example.com",
    "reason": "bounce",
    "source": "automatic",
    "workspaceId": "ws_abc123",
    "workspaceName": "Acme Corp",
    "metadata": {
      "bounceType": "Permanent",
      "bounceSubType": "General",
      "diagnosticCode": "550 5.1.1 User unknown",
      "messageId": "msg_789",
      "originalRecipient": "bounced@example.com"
    },
    "createdAt": "2024-02-01T14:30:00Z",
    "expiresAt": null,
    "history": [
      {
        "action": "created",
        "timestamp": "2024-02-01T14:30:00Z",
        "details": "Hard bounce received from SES"
      }
    ]
  }
}

Add Email to Suppression List

Manually add an email address to the suppression list.

POST /api/admin/email/suppression

Request Body

Field	Type	Required	Description
`email`	string	Yes	Email address to suppress
`reason`	string	Yes	Suppression reason
`workspaceId`	string	No	Associated workspace ID
`metadata`	object	No	Additional metadata
`expiresAt`	string	No	Expiration date (ISO 8601)

Request Example

curl -X POST "https://api.yourdomain.com/api/admin/email/suppression" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "spam@example.com",
    "reason": "manual",
    "workspaceId": "ws_abc123",
    "metadata": {
      "note": "Known spam trap",
      "addedBy": "admin@platform.com"
    }
  }'

Response Example

{
  "success": true,
  "data": {
    "id": "sup_12347",
    "email": "spam@example.com",
    "reason": "manual",
    "source": "admin",
    "workspaceId": "ws_abc123",
    "metadata": {
      "note": "Known spam trap",
      "addedBy": "admin@platform.com"
    },
    "createdAt": "2024-02-04T10:30:00Z",
    "expiresAt": null
  }
}

Bulk Add to Suppression List

Add multiple email addresses to the suppression list in a single request.

POST /api/admin/email/suppression/bulk

Request Body

Field	Type	Required	Description
`emails`	array	Yes	Array of email objects
`emails[].email`	string	Yes	Email address to suppress
`emails[].reason`	string	Yes	Suppression reason
`emails[].workspaceId`	string	No	Associated workspace ID
`emails[].metadata`	object	No	Additional metadata

Request Example

curl -X POST "https://api.yourdomain.com/api/admin/email/suppression/bulk" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      {
        "email": "bounce1@example.com",
        "reason": "bounce",
        "workspaceId": "ws_abc123"
      },
      {
        "email": "bounce2@example.com",
        "reason": "bounce",
        "workspaceId": "ws_abc123"
      }
    ]
  }'

Response Example

{
  "success": true,
  "data": {
    "processed": 2,
    "succeeded": 2,
    "failed": 0,
    "entries": [
      {
        "id": "sup_12348",
        "email": "bounce1@example.com",
        "status": "created"
      },
      {
        "id": "sup_12349",
        "email": "bounce2@example.com",
        "status": "created"
      }
    ]
  }
}

Remove Email from Suppression List

Remove an email address from the suppression list.

DELETE /api/admin/email/suppression/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Suppression entry ID

Query Parameters

Parameter	Type	Required	Description
`reason`	string	Yes	Reason for removal

Request Example

curl -X DELETE "https://api.yourdomain.com/api/admin/email/suppression/sup_12345?reason=Verified%20valid%20email" \
  -H "Authorization: Bearer <admin_token>"

Response Example

{
  "success": true,
  "data": {
    "id": "sup_12345",
    "email": "bounced@example.com",
    "removed": true,
    "removedAt": "2024-02-04T10:35:00Z",
    "removalReason": "Verified valid email"
  }
}

Check Email Suppression Status

Check if an email address is on the suppression list.

GET /api/admin/email/suppression/check

Query Parameters

Parameter	Type	Required	Description
`email`	string	Yes	Email address to check

Request Example

curl -X GET "https://api.yourdomain.com/api/admin/email/suppression/check?email=user@example.com" \
  -H "Authorization: Bearer <admin_token>"

Response Example

{
  "success": true,
  "data": {
    "email": "user@example.com",
    "suppressed": true,
    "entry": {
      "id": "sup_12345",
      "reason": "bounce",
      "createdAt": "2024-02-01T14:30:00Z"
    }
  }
}

If not suppressed:

{
  "success": true,
  "data": {
    "email": "user@example.com",
    "suppressed": false,
    "entry": null
  }
}

Get Suppression Statistics

Retrieve statistics about the suppression list.

GET /api/admin/email/suppression/stats

Request Example

curl -X GET "https://api.yourdomain.com/api/admin/email/suppression/stats" \
  -H "Authorization: Bearer <admin_token>"

Response Example

{
  "success": true,
  "data": {
    "total": 1250,
    "byReason": {
      "bounce": 890,
      "complaint": 45,
      "unsubscribe": 280,
      "manual": 30,
      "invalid": 5
    },
    "bySource": {
      "automatic": 935,
      "user_action": 280,
      "admin": 35
    },
    "recentAdditions": {
      "last24Hours": 12,
      "last7Days": 89,
      "last30Days": 245
    }
  }
}

Error Responses

Invalid Email

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid email address format"
  }
}

Already Suppressed

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "Email is already on the suppression list",
    "data": {
      "id": "sup_12345",
      "reason": "bounce"
    }
  }
}

Not Found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Suppression entry not found"
  }
}

SDK Example

import { createAdminEmailClient } from '@/lib/admin/email-client';

const adminEmail = createAdminEmailClient();

// List suppressed emails
const suppressed = await adminEmail.suppression.list({
  reason: 'bounce',
  limit: 50
});

// Check if email is suppressed
const check = await adminEmail.suppression.check('user@example.com');

// Add email to suppression
await adminEmail.suppression.add({
  email: 'spam@example.com',
  reason: 'manual',
  workspaceId: 'ws_abc123',
  metadata: { note: 'Known spam trap' }
});

// Bulk add emails
await adminEmail.suppression.bulkAdd([
  { email: 'bounce1@example.com', reason: 'bounce' },
  { email: 'bounce2@example.com', reason: 'bounce' }
]);

// Remove from suppression
await adminEmail.suppression.remove('sup_12345', {
  reason: 'Verified valid email'
});

// Get statistics
const stats = await adminEmail.suppression.getStats();

Suppression List Management

On this page