Reputation Management Administrative endpoints for monitoring and managing email reputation flags
Administrative endpoints for monitoring email reputation across workspaces and managing reputation flags. These endpoints help maintain high deliverability rates by identifying and addressing reputation issues.
The reputation management system tracks email sending behavior and automatically flags workspaces that may be damaging the platform's sender reputation. Admins can view reputation metrics, manage flags, and take corrective actions.
Metric Description Threshold bounceRatePercentage of emails that bounced > 5% warning, > 10% critical complaintRatePercentage marked as spam > 0.1% warning, > 0.3% critical volumeSpikeSudden increase in send volume > 300% of baseline listQualityQuality of recipient lists Based on bounce/complaint patterns authenticationSPF/DKIM/DMARC compliance < 95% warning
Flag Severity Description high_bounce_ratewarning/critical Excessive bounce rate detected high_complaint_ratewarning/critical High spam complaint rate suspicious_volumewarning Unusual sending volume poor_list_qualitywarning Low-quality recipient list auth_failurewarning Authentication issues manual_reviewinfo Flagged for admin review sending_pausedcritical Sending temporarily disabled
/api/admin/email/reputation Retrieve all reputation flags across workspaces.
GET /api/admin/email/reputation Parameter Type Required Description pageinteger No Page number (default: 1) limitinteger No Items per page (default: 20, max: 100) severitystring No Filter by severity: info, warning, critical flagstring No Filter by flag type workspaceIdstring No Filter by workspace statusstring No Filter by status: open, acknowledged, resolved dateFromstring No Filter from date (ISO 8601) dateTostring No Filter to date (ISO 8601) sortBystring No Sort field: createdAt, severity sortOrderstring No Sort direction: asc or desc
curl -X GET "https://api.yourdomain.com/api/admin/email/reputation?severity=critical&status=open" \ -H "Authorization: Bearer <admin_token>" { "success" : true , "data" : [ { "id" : "flag_12345" , "workspaceId" : "ws_abc123" , "workspaceName" : "Acme Corp" , "flag" : "high_bounce_rate" , "severity" : "critical" , "status" : "open" , "message" : "Bounce rate of 12.5% exceeds critical threshold of 10%" , "metrics" : { "bounceRate" : 12.5 , "sentCount" : 1000 , "bounceCount" : 125 , "threshold" : 10.0 }, "createdAt" : "2024-02-04T08:00:00Z" , "acknowledgedAt" : null , "resolvedAt" : null , "acknowledgedBy" : null , "resolvedBy" : null }, { "id" : "flag_12346" , "workspaceId" : "ws_def456" , "workspaceName" : "TechStart Inc" , "flag" : "high_complaint_rate" , "severity" : "warning" , "status" : "acknowledged" , "message" : "Complaint rate of 0.15% exceeds warning threshold of 0.1%" , "metrics" : { "complaintRate" : 0.15 , "sentCount" : 5000 , "complaintCount" : 8 , "threshold" : 0.1 }, "createdAt" : "2024-02-03T14:30:00Z" , "acknowledgedAt" : "2024-02-03T15:00:00Z" , "resolvedAt" : null , "acknowledgedBy" : "admin@platform.com" , "resolvedBy" : null } ], "meta" : { "page" : 1 , "limit" : 20 , "total" : 15 , "totalPages" : 1 , "bySeverity" : { "critical" : 3 , "warning" : 10 , "info" : 2 } } } Retrieve detailed information about a specific reputation flag.
GET /api/admin/email/reputation/:id Parameter Type Required Description idstring Yes Reputation flag ID
curl -X GET "https://api.yourdomain.com/api/admin/email/reputation/flag_12345" \ -H "Authorization: Bearer <admin_token>" { "success" : true , "data" : { "id" : "flag_12345" , "workspaceId" : "ws_abc123" , "workspaceName" : "Acme Corp" , "workspaceSlug" : "acme-corp" , "flag" : "high_bounce_rate" , "severity" : "critical" , "status" : "open" , "message" : "Bounce rate of 12.5% exceeds critical threshold of 10%" , "description" : "This workspace has an unusually high bounce rate, indicating potential issues with their email list quality or acquisition practices." , "metrics" : { "bounceRate" : 12.5 , "sentCount" : 1000 , "bounceCount" : 125 , "hardBounces" : 98 , "softBounces" : 27 , "threshold" : 10.0 , "period" : "24h" }, "affectedDomains" : [ "acme.com" ], "recommendedActions" : [ "Review email list acquisition practices" , "Implement double opt-in" , "Clean email list using verification service" , "Pause sending until issue is resolved" ], "history" : [ { "action" : "created" , "timestamp" : "2024-02-04T08:00:00Z" , "details" : "Automatic flag created due to high bounce rate" } ], "createdAt" : "2024-02-04T08:00:00Z" , "acknowledgedAt" : null , "resolvedAt" : null , "acknowledgedBy" : null , "resolvedBy" : null } } Retrieve reputation metrics and flags for a specific workspace.
GET /api/admin/email/reputation/workspace/:workspaceId Parameter Type Required Description workspaceIdstring Yes Workspace ID
Parameter Type Required Description periodstring No Time period: 24h, 7d, 30d (default: 24h)
curl -X GET "https://api.yourdomain.com/api/admin/email/reputation/workspace/ws_abc123?period=7d" \ -H "Authorization: Bearer <admin_token>" { "success" : true , "data" : { "workspaceId" : "ws_abc123" , "workspaceName" : "Acme Corp" , "period" : "7d" , "metrics" : { "sentCount" : 15420 , "bounceCount" : 154 , "complaintCount" : 12 , "bounceRate" : 1.0 , "complaintRate" : 0.08 , "deliveryRate" : 99.0 , "authCompliance" : 99.5 }, "thresholds" : { "bounceRate" : { "warning" : 5.0 , "critical" : 10.0 }, "complaintRate" : { "warning" : 0.1 , "critical" : 0.3 } }, "status" : "healthy" , "flags" : [ { "id" : "flag_12345" , "flag" : "high_bounce_rate" , "severity" : "critical" , "status" : "open" , "createdAt" : "2024-02-04T08:00:00Z" } ], "trend" : { "bounceRate" : "increasing" , "complaintRate" : "stable" , "volume" : "increasing" } } } Acknowledge a reputation flag to indicate it has been reviewed.
POST /api/admin/email/reputation/:id/acknowledge Parameter Type Required Description idstring Yes Reputation flag ID
Field Type Required Description notesstring No Optional notes about the acknowledgment
curl -X POST "https://api.yourdomain.com/api/admin/email/reputation/flag_12345/acknowledge" \ -H "Authorization: Bearer <admin_token>" \ -H "Content-Type: application/json" \ -d '{ "notes": "Reviewed with workspace admin, implementing list cleaning" }' { "success" : true , "data" : { "id" : "flag_12345" , "status" : "acknowledged" , "acknowledgedAt" : "2024-02-04T10:30:00Z" , "acknowledgedBy" : "admin@platform.com" , "notes" : "Reviewed with workspace admin, implementing list cleaning" } } Mark a reputation flag as resolved.
POST /api/admin/email/reputation/:id/resolve Parameter Type Required Description idstring Yes Reputation flag ID
Field Type Required Description resolutionstring Yes Resolution description notesstring No Additional notes
curl -X POST "https://api.yourdomain.com/api/admin/email/reputation/flag_12345/resolve" \ -H "Authorization: Bearer <admin_token>" \ -H "Content-Type: application/json" \ -d '{ "resolution": "bounce_rate_improved", "notes": "Workspace cleaned their list, bounce rate now at 2%" }' { "success" : true , "data" : { "id" : "flag_12345" , "status" : "resolved" , "resolvedAt" : "2024-02-04T14:00:00Z" , "resolvedBy" : "admin@platform.com" , "resolution" : "bounce_rate_improved" , "notes" : "Workspace cleaned their list, bounce rate now at 2%" } } Manually create a reputation flag for a workspace.
POST /api/admin/email/reputation Field Type Required Description workspaceIdstring Yes Workspace ID flagstring Yes Flag type severitystring Yes Severity: info, warning, critical messagestring Yes Flag message descriptionstring No Detailed description recommendedActionsarray No List of recommended actions
curl -X POST "https://api.yourdomain.com/api/admin/email/reputation" \ -H "Authorization: Bearer <admin_token>" \ -H "Content-Type: application/json" \ -d '{ "workspaceId": "ws_abc123", "flag": "manual_review", "severity": "warning", "message": "Unusual sending patterns detected", "description": "Workspace showing irregular sending times and volume spikes", "recommendedActions": [ "Contact workspace admin", "Review recent campaign details" ] }' { "success" : true , "data" : { "id" : "flag_12347" , "workspaceId" : "ws_abc123" , "flag" : "manual_review" , "severity" : "warning" , "status" : "open" , "message" : "Unusual sending patterns detected" , "createdAt" : "2024-02-04T10:30:00Z" } } Temporarily pause email sending for a workspace due to reputation issues.
POST /api/admin/email/reputation/workspace/:workspaceId/pause Parameter Type Required Description workspaceIdstring Yes Workspace ID
Field Type Required Description reasonstring Yes Reason for pausing durationstring No Pause duration: 1h, 24h, 7d, or indefinite notesstring No Additional notes
curl -X POST "https://api.yourdomain.com/api/admin/email/reputation/workspace/ws_abc123/pause" \ -H "Authorization: Bearer <admin_token>" \ -H "Content-Type: application/json" \ -d '{ "reason": "Critical bounce rate affecting platform reputation", "duration": "24h", "notes": "Workspace must clean list before resuming" }' { "success" : true , "data" : { "workspaceId" : "ws_abc123" , "sendingPaused" : true , "pausedAt" : "2024-02-04T10:30:00Z" , "pausedBy" : "admin@platform.com" , "reason" : "Critical bounce rate affecting platform reputation" , "duration" : "24h" , "resumesAt" : "2024-02-05T10:30:00Z" , "flagId" : "flag_12348" } } Resume email sending for a paused workspace.
POST /api/admin/email/reputation/workspace/:workspaceId/resume Parameter Type Required Description workspaceIdstring Yes Workspace ID
Field Type Required Description reasonstring Yes Reason for resuming
curl -X POST "https://api.yourdomain.com/api/admin/email/reputation/workspace/ws_abc123/resume" \ -H "Authorization: Bearer <admin_token>" \ -H "Content-Type: application/json" \ -d '{ "reason": "Workspace has cleaned their list and bounce rate is now acceptable" }' { "success" : true , "data" : { "workspaceId" : "ws_abc123" , "sendingPaused" : false , "resumedAt" : "2024-02-04T14:00:00Z" , "resumedBy" : "admin@platform.com" , "reason" : "Workspace has cleaned their list and bounce rate is now acceptable" } } Retrieve overall reputation metrics for the entire platform.
GET /api/admin/email/reputation/overview Parameter Type Required Description periodstring No Time period: 24h, 7d, 30d (default: 24h)
curl -X GET "https://api.yourdomain.com/api/admin/email/reputation/overview?period=7d" \ -H "Authorization: Bearer <admin_token>" { "success" : true , "data" : { "period" : "7d" , "platformMetrics" : { "totalSent" : 154200 , "totalBounced" : 1542 , "totalComplaints" : 123 , "bounceRate" : 1.0 , "complaintRate" : 0.08 , "deliveryRate" : 99.0 }, "flags" : { "total" : 15 , "open" : 8 , "acknowledged" : 4 , "resolved" : 3 , "bySeverity" : { "critical" : 3 , "warning" : 10 , "info" : 2 } }, "workspaces" : { "total" : 45 , "healthy" : 38 , "flagged" : 5 , "paused" : 2 }, "trends" : { "bounceRate" : "stable" , "complaintRate" : "decreasing" , "flagCount" : "increasing" } } } { "success" : false , "error" : { "code" : "NOT_FOUND" , "message" : "Reputation flag not found" } } { "success" : false , "error" : { "code" : "BAD_REQUEST" , "message" : "Cannot resolve flag that is not acknowledged" , "details" : { "currentStatus" : "open" , "requiredStatus" : "acknowledged" } } } { "success" : false , "error" : { "code" : "NOT_FOUND" , "message" : "Workspace not found" } } import { createAdminEmailClient } from '@/lib/admin/email-client' ; const adminEmail = createAdminEmailClient (); // List all reputation flags const flags = await adminEmail.reputation. list ({ severity: 'critical' , status: 'open' }); // Get specific flag details const flag = await adminEmail.reputation. get ( 'flag_12345' ); // Get workspace reputation const workspaceRep = await adminEmail.reputation. getWorkspace ( 'ws_abc123' , { period: '7d' }); // Acknowledge a flag await adminEmail.reputation. acknowledge ( 'flag_12345' , { notes: 'Reviewed with workspace admin' }); // Resolve a flag await adminEmail.reputation. resolve ( 'flag_12345' , { resolution: 'bounce_rate_improved' , notes: 'Issue resolved after list cleaning' }); // Create manual flag await adminEmail.reputation. create ({ workspaceId: 'ws_abc123' , flag: 'manual_review' , severity: 'warning' , message: 'Unusual sending patterns detected' }); // Pause workspace sending await adminEmail.reputation. pauseWorkspace ( 'ws_abc123' , { reason: 'Critical bounce rate' , duration: '24h' }); // Resume workspace sending await adminEmail.reputation. resumeWorkspace ( 'ws_abc123' , { reason: 'Issue resolved' }); // Get platform overview const overview = await adminEmail.reputation. getOverview ({ period: '7d' });