Skip to main content

​
Get bounces

curl -u 'username:password' 'https://listmonk.mysite.com/api/bounces' \
  -G \
  -d 'page=1' \
  -d 'per_page=50' \
  -d 'campaign_id=1'
Retrieves bounce records with pagination and filtering. Authentication: Required
Permission: bounces:get

​
Query Parameters

​
page
integer
default:"1"
Page number for pagination
​
per_page
integer
default:"20"
Number of results per page
​
campaign_id
integer
Filter by campaign ID
​
source
string
Filter by bounce source (e.g., “ses”, “sendgrid”, “postmark”, “manual”)
​
order_by
string
default:"created_at"
Field to order by
​
order
string
default:"desc"
Sort order: asc or desc

​
Response

​
data
object

​
Get bounce

curl -u 'username:password' 'https://listmonk.mysite.com/api/bounces/1'
Retrieves a single bounce record by ID. Authentication: Required
Permission: bounces:get

​
Path Parameters

​
id
integer
required
Bounce ID

​
Response

​
data
object
Returns a single bounce object

​
Delete bounce

curl -u 'username:password' -X DELETE 'https://listmonk.mysite.com/api/bounces/1'
Deletes a single bounce record. Authentication: Required
Permission: bounces:manage

​
Path Parameters

​
id
integer
required
Bounce ID

​
Response

​
data
boolean
Returns true on successful deletion

​
Delete bounces (bulk)

curl -u 'username:password' -X DELETE 'https://listmonk.mysite.com/api/bounces?id=1&id=2&id=3'
Deletes multiple bounce records. Authentication: Required
Permission: bounces:manage

​
Query Parameters

​
id
integer
Bounce ID to delete (can be specified multiple times)
​
all
boolean
If true, deletes all bounce records

​
Response

​
data
boolean
Returns true on successful deletion

​
Blocklist bounced subscribers

curl -u 'username:password' -X PUT 'https://listmonk.mysite.com/api/bounces/blocklist'
Blocklists all subscribers who have hard bounces or complaints. Authentication: Required
Permission: bounces:manage

​
Response

​
data
boolean
Returns true on success
This operation blocklists subscribers with hard bounces or complaint bounces. Subscribers with soft bounces are not affected.

​
Record bounce (webhook)

curl -u 'username:password' 'https://listmonk.mysite.com/webhooks/bounce' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "hard",
    "email": "bounce@example.com",
    "campaign_uuid": "5e6e3e8f-6b5a-4c8d-9c3a-1f2e3c4b5a6d",
    "source": "manual",
    "meta": {"reason": "Mailbox does not exist"}
  }'
Manually records a bounce event. This endpoint can be used for custom bounce handling or integration with third-party services. Authentication: Required
Permission: webhooks:post_bounce

​
Request Body

​
type
string
required
Bounce type:
  • hard: Permanent delivery failure (mailbox doesn’t exist, domain invalid)
  • soft: Temporary failure (mailbox full, server unavailable)
  • complaint: Spam complaint
​
email
string
Email address that bounced (either email or subscriber_uuid required)
​
subscriber_uuid
string
Subscriber UUID (either email or subscriber_uuid required)
​
campaign_uuid
string
Campaign UUID (optional)
​
source
string
default:"manual"
Source identifier (e.g., “manual”, “custom-webhook”)
​
meta
object
Additional metadata as JSON object
​
created_at
string
Bounce timestamp (ISO 8601 format, defaults to current time)

​
Response

​
data
boolean
Returns true on successful recording

​
Bounce Types

​
Hard Bounces

Permanent delivery failures that indicate the email address is invalid or no longer exists:
  • Mailbox does not exist
  • Invalid domain
  • Email address rejected
Hard bounces should result in removing or blocklisting the subscriber to maintain sender reputation.

​
Soft Bounces

Temporary delivery failures that may succeed on retry:
  • Mailbox full
  • Server temporarily unavailable
  • Message too large
Soft bounces are typically retried. After multiple soft bounces, the subscriber may be treated as a hard bounce.

​
Complaints

When a recipient marks an email as spam:
  • Spam complaint via feedback loop
  • Abuse reports
Complaints should result in immediate unsubscription or blocklisting to comply with anti-spam regulations.

​
Bounce Webhooks

listmonk supports bounce webhooks from major email service providers:

​
Amazon SES

POST /webhooks/service/ses

​
SendGrid

POST /webhooks/service/sendgrid

​
Postmark

POST /webhooks/service/postmark

​
Forward Email

POST /webhooks/service/forwardemail
These webhooks automatically record bounces from the respective providers. Configure your email service provider to send bounce notifications to these endpoints.
Webhook URLs are public endpoints that don’t require authentication. Ensure your provider is configured with the correct signature verification for security.

Build docs developers (and LLMs) love

Get started for freeTalk to us