[SES-PHASE-1-6] - PLU-744: add admin whitelist endpoint

[m0nggh]

TL;DR

Adds an admin-only API endpoint to remove emails from the suppression list.

What changed?

A new /api/admin/email-suppression/whitelist GET endpoint has been added, protected by an isAdminOperation middleware check that returns a 403 if the request is not from a Plumber admin. The endpoint accepts a comma-separated emails query parameter, handles + characters that get decoded as spaces in query strings, and calls EmailSuppressionEntry.whitelistEmails to remove the specified emails from the suppression list. The operation is logged with the requested and successfully whitelisted emails.

How to test?

Note that this is to be done on Plumber admin: will release a PR on plumber admin to test on staging first
Refer to PR for the change

1. Make a request with a valid admin token:
2. Verify the response includes the whitelisted array and count.
3. Confirm that emails with + characters are handled correctly (e.g., b+1@example.com should not be mangled).
4. Attempt the same request without an admin token and confirm a 403 is returned (make the http call on Plumber app)
5. Omit the emails parameter or pass an empty value and confirm a 400 is returned.

Why make this change?

Emails can end up on the suppression list after a bounce or complaint, preventing legitimate users from receiving emails. This endpoint gives Plumber admins a way to manually remove specific emails from the suppression list without requiring direct database access.

[m0nggh]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• [SES-PHASE-1-9] - PLU-744: send attachments with ses #1636
• [SES-PHASE-1-8] - PLU-744: add bounce rate tracking (exploration) #1634
• [SES-PHASE-1-7] - PLU-744: add env vars for ses and sqs #1633
• [SES-PHASE-1-6] - PLU-744: add admin whitelist endpoint #1632 👈 (View in Graphite)
• [SES-PHASE-1-5] - PLU-744: add suppression check for ses send email #1631
• [SES-PHASE-1-4] - PLU-744: add consumer for sqs events #1630
• [SES-PHASE-1-3] - PLU-744: add ses event parser #1629
• [SES-PHASE-1-2] - PLU-744: add migration and email suppression model #1628
• [SES-PHASE-1-1] - PLU-744: add SES call and LD flag #1627
• feat/ses/trunk

This stack of pull requests is managed by Graphite. Learn more about stacking.

[linear]

PLU-744

[graphite-app]

Type assertion bug: req.query.emails can be a string array if the parameter is repeated in the URL (e.g., ?emails=a@x.com&emails=b@x.com). The code assumes it's always a string and calls .split(',') on it, which will throw TypeError: split is not a function if an array is passed.

const emailsParam = req.query.emails
if (!emailsParam || Array.isArray(emailsParam)) {
  res.status(400).json({ error: 'emails query parameter is required and must be a single value' })
  return
}
const emails = (emailsParam as string)
  .split(',')
  .map((e) => e.trim().replace(/ /g, '+'))
  .filter(Boolean)

Suggested change

	const emailsParam = req.query.emails as string
	if (!emailsParam) {
	res.status(400).json({ error: 'emails query parameter is required' })
	return
	}
	// `+` in query strings is decoded to a space; restore it since spaces
	// are not valid in email addresses. This lets callers paste URLs with
	// unencoded `+` characters directly.
	const emails = emailsParam
	.split(',')
	.map((e) => e.trim().replace(/ /g, '+'))
	const emailsParam = req.query.emails
	if (!emailsParam || Array.isArray(emailsParam)) {
	res.status(400).json({ error: 'emails query parameter is required and must be a single value' })
	return
	}
	const emails = (emailsParam as string)
	.split(',')
	.map((e) => e.trim().replace(/ /g, '+'))
	.filter(Boolean)

Spotted by Graphite



Is this helpful? React 👍 or 👎 to let us know.

[ogp-weeloong]

nit: zod this?

[ogp-weeloong]

to be extra safe, we should also add guardrails for this route to our WAF

[ogp-weeloong]

eh, why use a GET here?

For writes, it's more idiomatic to use POST / PUT / PATCH / DELETE. Primarily we're concerned about accidentlly exposing ourselves to CSRF attacks.

The more important part is actually for POST requests, browsers put up the form resubmission warning.

For this case, POST is fine, but tbh we don't need to enforce resubmission warning; PUT or PATCH also OK. DELETE feels weird

[ogp-weeloong]

Ah ok as discussed - we're safe behind the plumber admin header but still kinda dangerous to propagate this in the code. would like to avoid if possible unless we have a really really strong use case.

[ogp-weeloong]

GET -> POST