asyncapi: 3.0.0 info: title: listmonk Bounce Webhooks version: '6.2.0' description: >- listmonk's event surface is INGRESS, not egress: a listmonk instance receives bounce and complaint events, it does not emit webhooks to subscribers of its own. This document models the two documented ingress channels — the generic bounce webhook API (`POST /webhooks/bounce`), which any script, mailbox reader or log processor can post to, and the six provider-specific receivers listmonk implements for Amazon SES, Azure Communication Services, Sendgrid / Twilio, Postmark, Forward Email and Lettermint. PROVENANCE: listmonk publishes no AsyncAPI document. This one was DERIVED by API Evangelist from listmonk's own bounce documentation (https://listmonk.app/docs/bounces/) and its OpenAPI. The endpoints, the payload fields, their types and their required-ness are as published; the AsyncAPI framing around them is ours. The provider-specific receivers accept each vendor's native bounce payload, whose schema belongs to that vendor and is deliberately not restated here. Bounce processing must be enabled in Settings -> Bounces before any of these endpoints becomes available. The generic webhook requires an API user with the `webhooks:post_bounce` permission. license: name: AGPL-3.0 url: https://github.com/knadh/listmonk/blob/master/LICENSE externalDocs: description: listmonk bounce processing documentation url: https://listmonk.app/docs/bounces/ servers: selfHosted: host: '{host}' protocol: https description: >- A self-hosted listmonk instance. listmonk operates no shared endpoint; substitute the operator's own hostname (listmonk's docs use `listmonk.yoursite.com`). variables: host: default: listmonk.yoursite.com description: Hostname of the listmonk deployment. channels: bounceWebhook: address: /webhooks/bounce title: Generic bounce webhook description: >- Record a bounce event with custom scripting — from reading a mailbox, a database, or mail server logs. Requires authentication with an API user holding the `webhooks:post_bounce` permission. messages: bounceEvent: $ref: '#/components/messages/BounceEvent' sesWebhook: address: /webhooks/service/ses title: Amazon SES bounce notifications description: >- Receives Amazon SES / SNS bounce and complaint notifications. listmonk documents SES automatic bounce processing as the recommended way to maintain sender reputation. messages: providerEvent: $ref: '#/components/messages/ProviderBounceEvent' azureWebhook: address: /webhooks/service/azure title: Azure Communication Services e-mail events description: Receives ACS e-mail delivery events via Azure Event Grid. Added in v6.2.0. messages: providerEvent: $ref: '#/components/messages/ProviderBounceEvent' sendgridWebhook: address: /webhooks/service/sendgrid title: Sendgrid / Twilio signed event webhook messages: providerEvent: $ref: '#/components/messages/ProviderBounceEvent' postmarkWebhook: address: /webhooks/service/postmark title: Postmark webhook messages: providerEvent: $ref: '#/components/messages/ProviderBounceEvent' forwardEmailWebhook: address: /webhooks/service/forwardemail title: Forward Email webhook messages: providerEvent: $ref: '#/components/messages/ProviderBounceEvent' lettermintWebhook: address: /webhooks/service/lettermint title: Lettermint webhook description: Added in v6.1.0. messages: providerEvent: $ref: '#/components/messages/ProviderBounceEvent' operations: receiveBounceEvent: action: receive channel: $ref: '#/channels/bounceWebhook' title: Record a bounce event summary: listmonk receives a bounce event posted by an external script or system. messages: - $ref: '#/channels/bounceWebhook/messages/bounceEvent' receiveSesEvent: action: receive channel: $ref: '#/channels/sesWebhook' title: Receive an Amazon SES bounce notification receiveAzureEvent: action: receive channel: $ref: '#/channels/azureWebhook' title: Receive an Azure Communication Services e-mail event receiveSendgridEvent: action: receive channel: $ref: '#/channels/sendgridWebhook' title: Receive a Sendgrid signed event receivePostmarkEvent: action: receive channel: $ref: '#/channels/postmarkWebhook' title: Receive a Postmark webhook receiveForwardEmailEvent: action: receive channel: $ref: '#/channels/forwardEmailWebhook' title: Receive a Forward Email webhook receiveLettermintEvent: action: receive channel: $ref: '#/channels/lettermintWebhook' title: Receive a Lettermint webhook components: messages: BounceEvent: name: BounceEvent title: Bounce event contentType: application/json payload: $ref: '#/components/schemas/BounceEvent' ProviderBounceEvent: name: ProviderBounceEvent title: Provider-native bounce notification contentType: application/json summary: >- The upstream provider's own bounce/complaint payload, forwarded verbatim. listmonk parses each provider's native format. The schema belongs to the provider and is not restated here — see the provider's documentation linked from https://listmonk.app/docs/bounces/. schemas: BounceEvent: type: object required: - source - type properties: subscriber_uuid: type: string format: uuid description: >- The UUID of the subscriber. Either this or `email` is required. email: type: string format: email description: >- The e-mail of the subscriber. Either this or `subscriber_uuid` is required. campaign_uuid: type: string format: uuid description: UUID of the campaign for which the bounce happened. source: type: string description: 'A string indicating the source, eg: `api`, `my_script`.' examples: - api - my_script type: type: string enum: - hard - soft description: >- Bounce type. listmonk's docs note this currently has no effect on how the bounce is treated. meta: type: string description: >- An optional escaped JSON string with arbitrary metadata about the bounce event. examples: - email: user1@mail.com campaign_uuid: 9f86b50d-5711-41c8-ab03-bc91c43d711b source: api type: hard meta: '{"additional": "info"}' securitySchemes: basicAuth: type: userPassword description: >- HTTP Basic auth with an API user and token (`curl -u 'api_username:access_token'`). The API user must hold the `webhooks:post_bounce` permission. Provider-specific receivers instead validate the upstream provider's own signature or shared secret, configured in Settings -> Bounces.