Complaint Handling

Overview

The Complaints API provides endpoints for retrieving and analyzing email complaints received from email service providers (primarily Amazon SES). Complaints occur when recipients mark emails as spam or report abuse. Base URL: /complaint

Complaint Model

Complaints have the following structure:

id (UUID) - Unique complaint identifier
notification_id (UUID) - ID of the notification that generated the complaint
service_id (UUID) - Service that sent the notification
service_name (string) - Name of the service
ses_feedback_id (string) - Amazon SES feedback identifier
complaint_type (string) - Type of complaint (e.g., “abuse”, “fraud”, “virus”)
complaint_date (datetime) - When the complaint was filed
created_at (datetime) - When the complaint was recorded in Notify

Get All Complaints

Endpoint: GET /complaint Retrieve a paginated list of all complaints.

Query Parameters

page (integer, optional) - Page number (default: 1)

Response

Status: 200 OK

{
  "complaints": [
    {
      "id": "1234abcd-5678-90ef-ghij-klmnopqrstuv",
      "notification_id": "9876fedc-5432-10ba-9876-543210fedcba",
      "service_id": "6ce466d0-fd6a-11e5-82f5-e0accb9d11a6",
      "service_name": "Example Service",
      "ses_feedback_id": "0000014a3e9d7e96-12345678-abcd-efgh-ijkl-123456789abc-000000",
      "complaint_type": "abuse",
      "complaint_date": "2026-03-03T09:15:00.000000Z",
      "created_at": "2026-03-03T09:20:00.000000Z"
    },
    {
      "id": "abcd5678-1234-90ef-ghij-klmnopqrstuv",
      "notification_id": "fedc9876-5432-10ba-9876-543210fedcba",
      "service_id": "6ce466d0-fd6a-11e5-82f5-e0accb9d11a6",
      "service_name": "Example Service",
      "ses_feedback_id": "0000014a3e9d8f23-87654321-dcba-hgfe-lkji-987654321cba-000000",
      "complaint_type": "fraud",
      "complaint_date": "2026-03-02T14:30:00.000000Z",
      "created_at": "2026-03-02T14:35:00.000000Z"
    }
  ],
  "links": {
    "first": "/complaint?page=1",
    "last": "/complaint?page=5",
    "next": "/complaint?page=2",
    "prev": null
  }
}

Pagination

The response includes pagination links:

first - First page of results
last - Last page of results
next - Next page (null if on last page)
prev - Previous page (null if on first page)

Get Complaint Count by Date Range

Endpoint: GET /complaint/count-by-date-range Retrieve the count of complaints within a specified date range.

Query Parameters

start_date (string, optional) - Start date in YYYY-MM-DD format (default: today)
end_date (string, optional) - End date in YYYY-MM-DD format (default: today)

Response

Status: 200 OK

{
  "count": 42
}

Examples

Get Today’s Complaint Count

curl https://api.notifications.service.gov.uk/complaint/count-by-date-range

Response:

{
  "count": 5
}

Get Complaint Count for Specific Date Range

curl "https://api.notifications.service.gov.uk/complaint/count-by-date-range?start_date=2026-03-01&end_date=2026-03-07"

Response:

{
  "count": 42
}

Get Complaint Count for Single Day

curl "https://api.notifications.service.gov.uk/complaint/count-by-date-range?start_date=2026-03-03&end_date=2026-03-03"

Response:

{
  "count": 8
}

Complaint Types

Common complaint types reported by email providers:

abuse - Recipient reported the email as abusive
auth-failure - Authentication/authorization failure
fraud - Email reported as fraudulent or phishing
not-spam - Recipient indicated email is not spam (rare)
other - Other unspecified complaint type
virus - Email reported as containing malware

Usage Examples

Retrieve First Page of Complaints

curl https://api.notifications.service.gov.uk/complaint

Retrieve Specific Page

curl https://api.notifications.service.gov.uk/complaint?page=3

Get Weekly Complaint Statistics

curl "https://api.notifications.service.gov.uk/complaint/count-by-date-range?start_date=2026-02-24&end_date=2026-03-03"

Monitor Monthly Trends

curl "https://api.notifications.service.gov.uk/complaint/count-by-date-range?start_date=2026-02-01&end_date=2026-02-28"

Implementation Notes

Complaint Processing

Receipt: Complaints are received via Amazon SES SNS notifications
Recording: System creates a Complaint record linked to the original notification
Service Impact: High complaint rates may affect service sending reputation
Monitoring: Regular monitoring helps identify problematic templates or targeting

Best Practices

Monitor Daily: Check complaint counts daily to catch issues early
Investigate Spikes: Sudden increases may indicate template problems or list quality issues
Review Templates: High complaint rates for specific templates suggest content review needed
List Hygiene: Regular complaints from same addresses indicate list management issues

Rate Thresholds

Typical complaint rate thresholds:

Normal: < 0.1% complaint rate
Warning: 0.1% - 0.5% complaint rate
Critical: > 0.5% complaint rate