Workspace Email Monitoring

Administrative endpoints for viewing and monitoring email activity across all workspaces in the platform.

Base URL

/api/admin/email/workspaces

Endpoints

List Workspace Email Statistics

Retrieve email statistics for all workspaces with pagination and filtering.

GET /api/admin/email/workspaces

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`limit`	integer	No	Items per page (default: 20, max: 100)
`sortBy`	string	No	Sort field: `sentCount`, `receivedCount`, `bounceRate`, `createdAt`
`sortOrder`	string	No	Sort direction: `asc` or `desc` (default: `desc`)
`search`	string	No	Search by workspace name or ID
`dateFrom`	string	No	Filter from date (ISO 8601)
`dateTo`	string	No	Filter to date (ISO 8601)

Request Example

curl -X GET "https://api.yourdomain.com/api/admin/email/workspaces?page=1&limit=20&sortBy=sentCount&sortOrder=desc" \
  -H "Authorization: Bearer <admin_token>"

Response Example

{
  "success": true,
  "data": [
    {
      "workspaceId": "ws_abc123",
      "workspaceName": "Acme Corp",
      "slug": "acme-corp",
      "stats": {
        "sentCount": 15420,
        "receivedCount": 8930,
        "bounceCount": 154,
        "complaintCount": 12,
        "bounceRate": 1.0,
        "complaintRate": 0.08
      },
      "limits": {
        "dailySendLimit": 10000,
        "monthlySendLimit": 300000
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "lastActivityAt": "2024-02-04T08:45:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "totalPages": 3
  }
}

Get Workspace Email Details

Retrieve detailed email statistics for a specific workspace.

GET /api/admin/email/workspaces/:workspaceId

Path Parameters

Parameter	Type	Required	Description
`workspaceId`	string	Yes	Unique workspace identifier

Request Example

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

Response Example

{
  "success": true,
  "data": {
    "workspaceId": "ws_abc123",
    "workspaceName": "Acme Corp",
    "slug": "acme-corp",
    "owner": {
      "id": "user_xyz789",
      "email": "admin@acme.com",
      "name": "John Admin"
    },
    "stats": {
      "sentCount": 15420,
      "receivedCount": 8930,
      "bounceCount": 154,
      "complaintCount": 12,
      "deliveryCount": 15266,
      "openCount": 8234,
      "clickCount": 3241,
      "bounceRate": 1.0,
      "complaintRate": 0.08,
      "deliveryRate": 99.0,
      "openRate": 53.9,
      "clickRate": 21.2
    },
    "limits": {
      "dailySendLimit": 10000,
      "monthlySendLimit": 300000,
      "currentDaySent": 3420,
      "currentMonthSent": 45230
    },
    "domains": [
      {
        "domain": "acme.com",
        "verified": true,
        "dkimVerified": true,
        "spfVerified": true,
        "createdAt": "2024-01-15T10:30:00Z"
      }
    ],
    "createdAt": "2024-01-15T10:30:00Z",
    "lastActivityAt": "2024-02-04T08:45:00Z"
  }
}

Get Workspace Email History

Retrieve detailed email send/receive history for a workspace.

GET /api/admin/email/workspaces/:workspaceId/history

Path Parameters

Parameter	Type	Required	Description
`workspaceId`	string	Yes	Unique workspace identifier

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`limit`	integer	No	Items per page (default: 50, max: 200)
`type`	string	No	Filter by type: `sent`, `received`, `bounce`, `complaint`
`status`	string	No	Filter by status: `delivered`, `bounced`, `complained`, `pending`
`dateFrom`	string	No	Filter from date (ISO 8601)
`dateTo`	string	No	Filter to date (ISO 8601)
`email`	string	No	Filter by sender/recipient email

Request Example

curl -X GET "https://api.yourdomain.com/api/admin/email/workspaces/ws_abc123/history?type=sent&limit=50" \
  -H "Authorization: Bearer <admin_token>"

Response Example

{
  "success": true,
  "data": [
    {
      "id": "msg_12345",
      "type": "sent",
      "from": "noreply@acme.com",
      "to": ["user@example.com"],
      "subject": "Welcome to Acme",
      "status": "delivered",
      "sentAt": "2024-02-04T08:45:00Z",
      "deliveredAt": "2024-02-04T08:45:02Z",
      "messageId": "message-id@acme.com",
      "size": 2456
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 15420,
    "totalPages": 309
  }
}

Update Workspace Email Limits

Update sending limits for a specific workspace.

PATCH /api/admin/email/workspaces/:workspaceId/limits

Path Parameters

Parameter	Type	Required	Description
`workspaceId`	string	Yes	Unique workspace identifier

Request Body

Field	Type	Required	Description
`dailySendLimit`	integer	No	Daily email send limit
`monthlySendLimit`	integer	No	Monthly email send limit
`hourlySendLimit`	integer	No	Hourly email send limit

Request Example

curl -X PATCH "https://api.yourdomain.com/api/admin/email/workspaces/ws_abc123/limits" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "dailySendLimit": 20000,
    "monthlySendLimit": 500000
  }'

Response Example

{
  "success": true,
  "data": {
    "workspaceId": "ws_abc123",
    "limits": {
      "dailySendLimit": 20000,
      "monthlySendLimit": 500000,
      "hourlySendLimit": 1000
    },
    "updatedAt": "2024-02-04T10:30:00Z"
  }
}

Error Responses

Workspace Not Found

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

Invalid Limits

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid limit values",
    "details": {
      "dailySendLimit": "Must be between 100 and 100000"
    }
  }
}

SDK Example

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

const adminEmail = createAdminEmailClient();

// List all workspaces with email stats
const workspaces = await adminEmail.workspaces.list({
  page: 1,
  limit: 20,
  sortBy: 'sentCount',
  sortOrder: 'desc',
  dateFrom: '2024-01-01',
  dateTo: '2024-02-04'
});

// Get specific workspace details
const workspace = await adminEmail.workspaces.get('ws_abc123');

// Get email history
const history = await adminEmail.workspaces.getHistory('ws_abc123', {
  type: 'bounce',
  limit: 100
});

// Update workspace limits
await adminEmail.workspaces.updateLimits('ws_abc123', {
  dailySendLimit: 20000,
  monthlySendLimit: 500000
});

Workspace Email Monitoring

On this page