SES suppression list silently blocks a real customer

"""Audit the SES account-level suppression list and remove named addresses.

Reports by default. Removal requires --apply AND an explicit address, because
deleting an entry that still bounces re-suppresses it and the bounce counts
against the account reputation.
"""
import argparse
import logging
import sys

import boto3
from botocore.exceptions import ClientError

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("ses_suppression_audit")

COMPLAINT = "COMPLAINT"


def list_suppressed(client, reasons=None):
    """Yield every suppressed destination, following pagination."""
    kwargs = {"PageSize": 1000}
    if reasons:
        kwargs["Reasons"] = reasons
    token = None
    while True:
        if token:
            kwargs["NextToken"] = token
        page = client.list_suppressed_destinations(**kwargs)
        for item in page.get("SuppressedDestinationSummaries", []):
            yield item
        token = page.get("NextToken")
        if not token:
            return


def describe(client, address):
    """Return the suppression record for one address, or None."""
    try:
        return client.get_suppressed_destination(
            EmailAddress=address)["SuppressedDestination"]
    except ClientError as exc:
        if exc.response["Error"]["Code"] == "NotFoundException":
            return None
        raise


def should_remove(record):
    """Pure decision function. No API calls, so it is trivial to test.

    A complaint means the recipient pressed 'this is spam'. Removing that entry
    and mailing them again is how an account gets shut down, so it is never
    eligible no matter what the operator passed on the command line.
    """
    if record is None:
        return False, "not suppressed"
    if record.get("Reason") == COMPLAINT:
        return False, "suppressed for a complaint; do not re-mail"
    return True, "suppressed for a bounce; safe to remove if the mailbox is fixed"


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--region", default="us-east-1")
    ap.add_argument("--remove", nargs="*", default=[],
                    help="addresses to remove; each is checked individually")
    ap.add_argument("--apply", action="store_true", help="actually delete")
    args = ap.parse_args()

    ses = boto3.client("sesv2", region_name=args.region)

    account = ses.get_account()
    supp = account.get("SuppressionAttributes", {}).get("SuppressedReasons", [])
    log.info("account-level suppression is on for: %s", supp or "nothing")

    counts = {}
    for item in list_suppressed(ses):
        counts[item["Reason"]] = counts.get(item["Reason"], 0) + 1
    log.info("suppression list holds %s", counts or "no addresses")

    exit_code = 0
    for address in args.remove:
        record = describe(ses, address)
        ok, reason = should_remove(record)
        if not ok:
            log.warning("SKIP %s -- %s", address, reason)
            exit_code = 1
            continue
        log.info("%s %s -- %s (suppressed %s)",
                 "REMOVING" if args.apply else "WOULD REMOVE",
                 address, reason, record.get("LastUpdateTime"))
        if args.apply:
            ses.delete_suppressed_destination(EmailAddress=address)

    if not args.apply and args.remove:
        log.info("dry run -- pass --apply to actually delete")
    return exit_code


if __name__ == "__main__":
    sys.exit(main())

/**
 * Audit the SES account-level suppression list and remove named addresses.
 *
 * Reports by default. Removal requires --apply AND an explicit address, because
 * deleting an entry that still bounces re-suppresses it and the bounce counts
 * against the account reputation.
 */
import {
  SESv2Client,
  GetAccountCommand,
  ListSuppressedDestinationsCommand,
  GetSuppressedDestinationCommand,
  DeleteSuppressedDestinationCommand,
} from '@aws-sdk/client-sesv2';

const COMPLAINT = 'COMPLAINT';

async function* listSuppressed(client) {
  let NextToken;
  do {
    const page = await client.send(
      new ListSuppressedDestinationsCommand({ PageSize: 1000, NextToken }),
    );
    yield* page.SuppressedDestinationSummaries ?? [];
    NextToken = page.NextToken;
  } while (NextToken);
}

async function describe(client, address) {
  try {
    const out = await client.send(
      new GetSuppressedDestinationCommand({ EmailAddress: address }),
    );
    return out.SuppressedDestination;
  } catch (err) {
    if (err.name === 'NotFoundException') return null;
    throw err;
  }
}

/**
 * Pure decision function. No API calls, so it is trivial to test.
 *
 * A complaint means the recipient pressed 'this is spam'. Removing that entry
 * and mailing them again is how an account gets shut down, so it is never
 * eligible no matter what the operator passed on the command line.
 */
export function shouldRemove(record) {
  if (!record) return { ok: false, reason: 'not suppressed' };
  if (record.Reason === COMPLAINT) {
    return { ok: false, reason: 'suppressed for a complaint; do not re-mail' };
  }
  return { ok: true, reason: 'suppressed for a bounce; safe to remove if the mailbox is fixed' };
}

async function main() {
  const args = process.argv.slice(2);
  const apply = args.includes('--apply');
  const removeAt = args.indexOf('--remove');
  const remove = removeAt === -1 ? [] : args.slice(removeAt + 1).filter((a) => !a.startsWith('--'));
  const client = new SESv2Client({ region: process.env.AWS_REGION ?? 'us-east-1' });

  const account = await client.send(new GetAccountCommand({}));
  console.log('account-level suppression is on for:',
    account.SuppressionAttributes?.SuppressedReasons ?? 'nothing');

  const counts = {};
  for await (const item of listSuppressed(client)) {
    counts[item.Reason] = (counts[item.Reason] ?? 0) + 1;
  }
  console.log('suppression list holds', Object.keys(counts).length ? counts : 'no addresses');

  let exitCode = 0;
  for (const address of remove) {
    const record = await describe(client, address);
    const { ok, reason } = shouldRemove(record);
    if (!ok) {
      console.warn(`SKIP ${address} -- ${reason}`);
      exitCode = 1;
      continue;
    }
    console.log(`${apply ? 'REMOVING' : 'WOULD REMOVE'} ${address} -- ${reason}`);
    if (apply) {
      await client.send(new DeleteSuppressedDestinationCommand({ EmailAddress: address }));
    }
  }
  if (!apply && remove.length) console.log('dry run -- pass --apply to actually delete');
  process.exit(exitCode);
}

if (import.meta.url === `file://${process.argv[1]}`) main();

import pytest
from ses_suppression_audit import should_remove


def test_missing_address_is_not_removable():
    ok, reason = should_remove(None)
    assert ok is False
    assert "not suppressed" in reason


def test_complaint_is_never_removable():
    ok, reason = should_remove({"Reason": "COMPLAINT"})
    assert ok is False, "removing a complaint and re-mailing is how accounts get shut down"


def test_bounce_is_removable():
    ok, _ = should_remove({"Reason": "BOUNCE"})
    assert ok is True


@pytest.mark.parametrize("reason", ["COMPLAINT", "complaint".upper()])
def test_complaint_case_is_exact(reason):
    """SES returns the reason uppercase; this guards the comparison."""
    ok, _ = should_remove({"Reason": reason})
    assert ok is False

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { shouldRemove } from './ses-suppression-audit.mjs';

test('a missing address is not removable', () => {
  const { ok, reason } = shouldRemove(null);
  assert.equal(ok, false);
  assert.match(reason, /not suppressed/);
});

test('a complaint is never removable', () => {
  const { ok } = shouldRemove({ Reason: 'COMPLAINT' });
  assert.equal(ok, false, 'removing a complaint and re-mailing is how accounts get shut down');
});

test('a bounce is removable', () => {
  const { ok } = shouldRemove({ Reason: 'BOUNCE' });
  assert.equal(ok, true);
});