Email Administration API

The Email Administration API provides administrative endpoints for managing the email infrastructure across all workspaces. These endpoints allow platform administrators to monitor email activity, manage suppression lists, and handle reputation flags.

Overview

This API is designed for platform-level administration of email services. It provides visibility into cross-workspace email metrics, suppression list management, and reputation monitoring capabilities.

Base URL

/api/admin/email

Authentication

All admin email endpoints require authentication with an admin-privileged account. Include your session token in the request headers:

Authorization: Bearer <session_token>

Required Permissions

• admin role is required for all endpoints
• Some endpoints may require additional email:admin scope

Available Endpoints

Common Response Format

All responses follow a consistent JSON structure:

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

Error Responses

Error responses include descriptive codes and messages:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Admin access required"
  }
}

Error Codes

Rate Limits

Admin email endpoints have higher rate limits:

• 500 requests per minute per admin user
• 5000 requests per hour per admin user

Rate limit headers are included in all responses:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 495
X-RateLimit-Reset: 1704067200

Audit Logging

All admin email actions are automatically logged:

• Admin user who performed the action
• Timestamp
• Action type (VIEW, CREATE, UPDATE, DELETE)
• Resource affected
• Workspace ID (if applicable)
• Changes made (for updates)

SDK Example

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

const adminEmail = createAdminEmailClient();

// List all workspace email statistics
const workspaces = await adminEmail.workspaces.list({
  page: 1,
  limit: 50,
  sortBy: 'sentCount',
  sortOrder: 'desc'
});

// Add email to global suppression list
await adminEmail.suppression.add({
  email: 'bounced@example.com',
  reason: 'bounce',
  workspaceId: 'ws_123'
});

// Get reputation flags for a workspace
const reputation = await adminEmail.reputation.get('ws_123');