SES v2 ListContacts API — FilteredStatus does not match topic-level OPT_OUT contacts

The ListContacts API does not return contacts that have OPT_OUT in their TopicPreferences for a specific topic when using FilteredStatus: OPT_OUT combined with TopicFilter. It only returns contacts where UnsubscribeAll is true.

This contradicts the documented behavior in the SES List Management Guide, which shows FilteredStatus + TopicFilter as the intended way to query contacts by topic subscription status.

Relevant documentation:

• ListContacts API Reference
• ListContactsFilter schema (describes FilteredStatus and TopicFilter fields)
• TopicFilter schema (describes UseDefaultIfPreferenceUnavailable)
• SES List Management Guide (walkthrough example that shows FilteredStatus + TopicFilter used together to query contacts by topic subscription status)

The Developer Guide walkthrough explicitly demonstrates this usage pattern:

{
"ContactListName": "ExampleContactListName",
    "Filter": {
        "FilteredStatus": "OPT_IN",
        "TopicFilter": {
            "TopicName": "Cycling",
            "UseDefaultIfPreferenceUnavailable": true
        }
    },
    "PageSize": 50
}

Per that guide, this call should return contacts whose effective subscription status for the "Cycling" topic is OPT_IN. By the same logic, FilteredStatus: OPT_OUT with a TopicFilter should return contacts opted out of that topic — but it does not.

STEPS TO REPRODUCE:

Verify List and Topic Setup We have a contact list named ExampleContactList with a topic topic_1.

Verify Contact Preferences A contact exists with an explicit topic-level OPT_OUT preference. Verified via GetContact:

aws sesv2 get-contact --contact-list-name ExampleContactList --email-address "<REDACTED_EMAIL>" --region eu-central-1

Response:

{
    "ContactListName": "ExampleContactList",
    "EmailAddress": "<REDACTED_EMAIL>",
    "TopicPreferences": [
        {
            "TopicName": "topic_1",
            "SubscriptionStatus": "OPT_OUT"
        }
    ],
    "TopicDefaultPreferences": [
        {
            "TopicName": "topic_2",
            "SubscriptionStatus": "OPT_IN"
        },
        {
            "TopicName": "topic_3",
            "SubscriptionStatus": "OPT_IN"
        },
        {
            "TopicName": "topic_4",
            "SubscriptionStatus": "OPT_IN"
        },
        {
            "TopicName": "topic_5",
            "SubscriptionStatus": "OPT_IN"
        },
        {
            "TopicName": "topic_6",
            "SubscriptionStatus": "OPT_IN"
        },
        {
            "TopicName": "topic_7",
            "SubscriptionStatus": "OPT_IN"
        },
        {
            "TopicName": "topic_8",
            "SubscriptionStatus": "OPT_IN"
        }
    ],
    "UnsubscribeAll": false,
    "CreatedTimestamp": "2026-03-25T15:44:37.022000+03:00",
    "LastUpdatedTimestamp": "2026-03-27T16:47:56.368000+03:00"
}

Note: The contact has UnsubscribeAll: false and one explicit OPT_OUT entry in TopicPreferences for topic_1.

Query ListContacts Querying ListContacts with FilteredStatus: OPT_OUT and TopicFilter for that topic returns 0 contacts:

aws sesv2 list-contacts --contact-list-name ExampleContactList --filter '{"FilteredStatus":"OPT_OUT","TopicFilter":{"TopicName":"topic_1","UseDefaultIfPreferenceUnavailable":false}}' --region eu-central-1

Response:

{
    "Contacts": [],
    "NextToken": "[NEXT_TOKEN]"
}

Note: The contact above is not returned despite having an explicit OPT_OUT for topic_1.

EXPECTED BEHAVIOR:

Per the ListContactsFilter documentation and the List Management Guide walkthrough, the contact with TopicPreferences: [{ TopicName: "topic_1", SubscriptionStatus: "OPT_OUT" }] should be returned.

OBSERVED BEHAVIOR:

FilteredStatus: OPT_OUT only matches contacts where UnsubscribeAll: true. Topic-level OPT_OUT entries in TopicPreferences are ignored, making the TopicFilter field effectively non-functional for finding opted-out contacts.

ADDITIONAL OBSERVATION:

Omitting FilteredStatus while providing TopicFilter returns an HTTP 400 error with the message "Invalid FilteredStatus " — meaning the Filter object requires FilteredStatus.

This creates a catch-22: the field is required, but its value does not consider topic-level preferences. There is no API-native way to list contacts opted out of a specific topic. Per the Contact object schema, contacts expose both UnsubscribeAll and TopicPreferences, but FilteredStatus appears to only evaluate UnsubscribeAll.

IMPACT:

We are currently migrating from another provider to SES and need to sync topic-level unsubscribes bidirectionally across ~50,000 contacts and 10 topics. Due to this issue, we cannot use the ListContacts filter to efficiently query per-topic OPT_OUT contacts. We are forced to implement a workaround: fetching the entire contact list via a full paginated scan on every sync run and filtering in our application code by inspecting TopicPreferences entries.