Add webhook-based email analytics/suppression ingestion path to unblock provider adapters (blocking #29553)

[wakqasahmed]

Context

PR #29553 adds the minimal email-provider adapter seam (AdapterManager resolving EmailServiceWrapper's provider) discussed in #25367, with ghost-ses-email-adapter as the first intended consumer. It's currently blocked:

• @acburdine on Added email provider adapter wiring #29553 (comment): "the main blocker to a standardized email adapter pattern isn't the email sending bits itself, it's the analytics/suppression bits... Ghost polls Mailgun's Events API for that analytics/suppression data, and we'd need to refactor some stuff in Ghost internally to allow for webhooks to be utilized instead in order to unblock full adapter support."
• @9larsons on Added email provider adapter wiring #29553 (comment): applied the blocked label — "the core team will likely take this over or adapt contributions."
• @9larsons earlier on Add email adapter pattern for pluggable email providers #28247 (comment) gave the fuller diagnosis: email-analytics-provider-mailgun.js is coupled to Mailgun's Events polling API, while every other candidate provider (SES, Postmark, SendGrid, etc.) is webhook-based. An adapter can send fine but analytics (opens/clicks/delivered/bounced) and suppression silently go dark, because the poll loop has nothing to poll and the bounce/complaint suppression list never fills — so Ghost keeps emailing dead addresses.

Both threads point at the same structural fix: ghost/core/core/server/services/email-analytics/ needs a webhook ingestion path alongside (or instead of) the polling path, so a non-Mailgun adapter has somewhere to deliver events.

Proposal

Open this as its own tracked issue, decoupled from any specific adapter PR, so the scope is:

1. Add a webhook ingestion entry point to email-analytics-service.js / email-analytics-service-wrapper.js that accepts normalized delivery/open/click/bounce/complaint events from an adapter, independent of email-analytics-provider-mailgun.js's poll loop.
2. Feed suppression (bounce/complaint) events from that path into the same suppression list Mailgun polling currently populates, so adapters don't silently leave it empty.
3. Leave the Mailgun poll path untouched — this is additive, not a replacement — matching @9larsons' framing on Add email adapter pattern for pluggable email providers #28247 of "send-only seam, edges documented, scheduler untouched" as an achievable first slice.
4. Document (in the adapter interface docs, not just code comments) which events an adapter is expected to push and in what shape, so AdapterManager-based adapters have a contract to implement against.

Why file this separately

#29553 is blocked specifically because this refactor doesn't exist yet, and the fix isn't scoped to that PR's diff — it's core analytics plumbing. Tracking it here gives the core team (or contributors, per @9larsons' "adapt contributions" note) a concrete, reviewable unit of work, and gives #29553 (and any future adapter PR) a real merge path instead of an open-ended "we're looking into it."

Happy to help scope or prototype the webhook ingestion path against ghost-ses-email-adapter as a concrete test case if that's useful — SES already delivers bounce/complaint/delivery events via SNS webhooks, so it's a reasonably representative first adapter to validate the contract against.

References

• Added email provider adapter wiring #29553 (blocked, this issue is the unblock path)
• Add email adapter pattern for pluggable email providers #28247 (earlier adapter attempt, same blocker)
• ✨ Phase 2: SES Integration (1/3) - Amazon SES email provider for bulk newsletters #25367 (original adapter-pattern discussion)

[wakqasahmed]

For reference, linked this issue from the ghost-ses-email-adapter README alongside #29553: wakqasahmed/ghost-ses-email-adapter#77

[wakqasahmed]

Opened a draft prototype attached to this proposal: #29829. It's additive to the poll loop and converges on the same EmailEventProcessor the Mailgun path already writes through — posted for concrete review/discussion, not as a finished implementation. Details and open questions are in the PR description.

[acburdine]

@wakqasahmed thanks for filing this! I was out this past week but will make sure to look at this next week 👍🏻