Privacy & Security

Privacy Settings

listmonk provides comprehensive privacy controls to comply with GDPR, CAN-SPAM, and other privacy regulations.

Privacy settings are configured through Settings → Privacy in the admin UI.

Tracking Settings

privacy.individual_tracking

boolean

default:"false"

Enable individual subscriber tracking for campaign views and link clicks.When enabled:

Campaign analytics show unique subscriber counts
You can see which specific subscribers viewed campaigns or clicked links

When disabled:

Analytics show aggregate counts only
Individual subscriber activity is not recorded

Disabling individual tracking significantly improves privacy but reduces analytics granularity.

privacy.disable_tracking

boolean

default:"false"

Completely disable all tracking pixels and link click tracking.

When enabled, you will have no campaign analytics at all. This is the most privacy-friendly option.

privacy.record_optin_ip

boolean

default:"false"

Record subscriber IP addresses during opt-in confirmation.Useful for:

Compliance proof of opt-in
Fraud detection
Geographic analytics

Unsubscribe Settings

privacy.unsubscribe_header

boolean

default:"true"

Add List-Unsubscribe and List-Unsubscribe-Post headers to campaign emails.These headers enable:

One-click unsubscribe in Gmail, Outlook, and other email clients
Improved deliverability and sender reputation
Compliance with RFC 8058

Recommended to keep enabled for better deliverability.

Subscriber Self-Service

privacy.allow_blocklist

boolean

default:"true"

Allow subscribers to blocklist themselves, preventing re-subscription.When blocklisted:

Subscriber is permanently removed
Email address cannot be added again (even through imports)
Complies with unsubscribe requests

privacy.allow_export

boolean

default:"true"

Allow subscribers to export their data through the subscription management page.Exports include (based on exportable configuration):

Profile information
Subscription status
Campaign views
Link clicks

privacy.allow_wipe

boolean

default:"true"

Allow subscribers to completely wipe their data from the system.

This is a destructive action that cannot be undone. All subscriber data, including analytics, is permanently deleted.

privacy.allow_preferences

boolean

default:"true"

Allow subscribers to manage their list subscriptions and preferences.Enables the public subscription management page where subscribers can:

Subscribe/unsubscribe from specific lists
Update their profile information
Access export and wipe features

Data Export Configuration

privacy.exportable

array

Define which data types subscribers can export.Available options:

profile - Name, email, attributes, and other profile data
subscriptions - List subscription status and dates
campaign_views - History of viewed campaigns
link_clicks - History of clicked links

Example:

["profile", "subscriptions"]

Domain Filtering

Control which email domains can subscribe to your lists.

privacy.domain_blocklist

array

default:"[]"

List of email domains to block from subscribing.Useful for:

Blocking disposable email services
Preventing spam subscriptions
Blocking competitor domains

Example:

["tempmail.com", "guerrillamail.com", "10minutemail.com"]

privacy.domain_allowlist

array

default:"[]"

List of email domains allowed to subscribe. When set, only these domains are permitted.

Allowlist takes precedence over blocklist. If allowlist is set, blocklist is ignored.

Use cases:

Internal company newsletters (only @company.com)
Exclusive communities
Educational institutions

Example:

["company.com", "partner.com"]

Domain Filter Examples

{
  "privacy.domain_blocklist": [
    "tempmail.com",
    "guerrillamail.com",
    "mailinator.com",
    "10minutemail.com",
    "throwaway.email"
  ]
}

CAPTCHA

Protect public subscription forms from bots and spam.

Altcha (Privacy-Friendly)

Altcha is a proof-of-work CAPTCHA that doesn’t track users or require external services.

security.captcha.altcha.enabled

boolean

default:"false"

Enable Altcha CAPTCHA on public subscription forms.

security.captcha.altcha.complexity

integer

default:"300000"

Computational complexity of the proof-of-work challenge.

Higher values = more difficult for bots, but slower for users
Recommended range: 50,000 to 500,000
Default (300,000) takes ~1-2 seconds on modern devices

{
  "security.captcha": {
    "altcha": {
      "enabled": true,
      "complexity": 300000
    }
  }
}

HCaptcha

HCaptcha is a privacy-focused alternative to Google reCAPTCHA.

security.captcha.hcaptcha.enabled

boolean

default:"false"

Enable HCaptcha on public subscription forms.

security.captcha.hcaptcha.key

string

required

HCaptcha site key from your HCaptcha account.

security.captcha.hcaptcha.secret

string

required

HCaptcha secret key from your HCaptcha account.

Create HCaptcha Account

Add New Site

In the HCaptcha dashboard, add your listmonk domain

Get Keys

Copy the Site Key and Secret Key

Configure listmonk

Enter the keys in Settings → Security → CAPTCHA

{
  "security.captcha": {
    "hcaptcha": {
      "enabled": true,
      "key": "your-site-key",
      "secret": "your-secret-key"
    }
  }
}

Only one CAPTCHA provider can be active at a time. If both are enabled, HCaptcha takes precedence.

CORS Configuration

Configure Cross-Origin Resource Sharing (CORS) for API access from web applications.

security.cors_origins

array

default:"[]"

List of origins allowed to make cross-origin requests to the listmonk API.Examples:

Specific domains: ["https://example.com", "https://app.example.com"]
Wildcard (not recommended): ["*"]

Only add trusted domains. Using ”*” allows any website to access your API.

{
  "security.cors_origins": [
    "https://example.com",
    "https://app.example.com",
    "https://admin.example.com"
  ]
}

Bounce Management

Handle bounced emails to maintain list hygiene and sender reputation.

Bounce Actions

Configure automatic actions for different bounce types:

{
  "bounce.actions": {
    "soft": {
      "count": 2,
      "action": "none"
    },
    "hard": {
      "count": 1,
      "action": "blocklist"
    },
    "complaint": {
      "count": 1,
      "action": "blocklist"
    }
  }
}

bounce.actions.soft.count

integer

default:"2"

Number of soft bounces before taking action.

bounce.actions.soft.action

string

default:"none"

Action to take after soft bounce threshold.Options: none, blocklist

bounce.actions.hard.count

integer

default:"1"

Number of hard bounces before taking action.

bounce.actions.hard.action

string

default:"blocklist"

Action to take after hard bounce threshold.Options: none, blocklist

bounce.actions.complaint.count

integer

default:"1"

Number of spam complaints before taking action.

bounce.actions.complaint.action

string

default:"blocklist"

Action to take after complaint threshold.Options: none, blocklist

Bounce Webhooks

bounce.webhooks_enabled

boolean

default:"false"

Enable bounce webhook endpoint at /webhooks/bounce.

This endpoint should be protected behind authentication or IP filtering.

Provider-Specific Bounce Handling

AWS SES

bounce.ses_enabled

boolean

default:"false"

Enable AWS SES SNS bounce webhook at /webhooks/service/ses.

Sendgrid

bounce.sendgrid_enabled

boolean

default:"false"

Enable Sendgrid bounce webhook at /webhooks/service/sendgrid.

bounce.sendgrid_key

string

default:""

Sendgrid webhook verification key for authenticating bounce notifications.

Postmark

bounce.postmark.enabled

boolean

default:"false"

Enable Postmark bounce webhook at /webhooks/service/postmark.

bounce.postmark.username

string

default:""

HTTP Basic Auth username for Postmark webhook.

bounce.postmark.password

string

default:""

HTTP Basic Auth password for Postmark webhook.

ForwardEmail

bounce.forwardemail.enabled

boolean

default:"false"

Enable ForwardEmail bounce webhook.

bounce.forwardemail.key

string

default:""

ForwardEmail webhook verification key.

Mailbox Polling

listmonk can poll a mailbox for bounce messages:

{
  "bounce.mailboxes": [
    {
      "enabled": true,
      "type": "pop",
      "host": "pop.yoursite.com",
      "port": 995,
      "auth_protocol": "userpass",
      "username": "[email protected]",
      "password": "password",
      "return_path": "[email protected]",
      "scan_interval": "15m",
      "tls_enabled": true,
      "tls_skip_verify": false
    }
  ]
}

Currently, only one mailbox is supported. POP3 is the only supported protocol.

Appearance Customization

Customize the look and feel of admin and public pages with custom CSS and JavaScript.

appearance.admin.custom_css

string

default:""

Custom CSS applied to the admin interface.

Be careful with custom CSS as it can break the UI layout.

appearance.admin.custom_js

string

default:""

Custom JavaScript applied to the admin interface.

Custom JavaScript runs with full admin privileges. Only use trusted code.

appearance.public.custom_css

string

default:""

Custom CSS applied to public pages (subscription management, archive).

appearance.public.custom_js

string

default:""

Custom JavaScript applied to public pages.

Privacy Compliance Checklist

Review Tracking Settings

Decide if you need individual tracking or can use aggregate analytics only.

Enable Subscriber Rights

Ensure allow_preferences, allow_export, and allow_wipe are enabled for GDPR compliance.

Configure Unsubscribe

Keep unsubscribe_header enabled for one-click unsubscribe support.

Set Up Bounce Handling

Configure bounce webhooks or mailbox polling to automatically remove invalid addresses.

Add CAPTCHA

Enable Altcha or HCaptcha to prevent bot subscriptions.

Document Data Retention

Create a privacy policy documenting what data you collect and how long you retain it.

Best Practices

Minimize Data Collection

Only track what you need. Consider disabling individual tracking if not required.

Enable Self-Service

Allow subscribers to manage their preferences, export data, and wipe their information.

Handle Bounces

Set up bounce handling to automatically clean your list and maintain sender reputation.

Use CAPTCHA

Protect subscription forms from spam and bot attacks.

Regular Audits

Periodically review privacy settings and ensure compliance with regulations.

Document Everything

Maintain clear documentation of your privacy practices and data handling.

Get Started

Core Features

Configuration

Advanced

Development

Privacy & Security

Privacy Settings

Tracking Settings

Unsubscribe Settings

Subscriber Self-Service

Data Export Configuration

Domain Filtering

Domain Filter Examples

CAPTCHA

Altcha (Privacy-Friendly)

HCaptcha

CORS Configuration

Bounce Management

Bounce Actions

Bounce Webhooks

Provider-Specific Bounce Handling

AWS SES

Sendgrid

Postmark

ForwardEmail

Mailbox Polling

Appearance Customization

Privacy Compliance Checklist

Best Practices

Minimize Data Collection

Enable Self-Service

Handle Bounces

Use CAPTCHA

Regular Audits

Document Everything

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Advanced

Development

​Privacy Settings

​Tracking Settings

​Unsubscribe Settings

​Subscriber Self-Service

​Data Export Configuration

​Domain Filtering

​Domain Filter Examples

​CAPTCHA

​Altcha (Privacy-Friendly)

​HCaptcha

​CORS Configuration

​Bounce Management

​Bounce Actions

​Bounce Webhooks

​Provider-Specific Bounce Handling

​AWS SES

​Sendgrid

​Postmark

​ForwardEmail

​Mailbox Polling

​Appearance Customization

​Privacy Compliance Checklist

​Best Practices

Minimize Data Collection

Enable Self-Service

Handle Bounces

Use CAPTCHA

Regular Audits

Document Everything

Build docs developers (and LLMs) love

Privacy Settings

Tracking Settings

Unsubscribe Settings

Subscriber Self-Service

Data Export Configuration

Domain Filtering

Domain Filter Examples

CAPTCHA

Altcha (Privacy-Friendly)

HCaptcha

CORS Configuration

Bounce Management

Bounce Actions

Bounce Webhooks

Provider-Specific Bounce Handling

AWS SES

Sendgrid

Postmark

ForwardEmail

Mailbox Polling

Appearance Customization

Privacy Compliance Checklist

Best Practices