CAN-SPAM Compliance

Overview

PushMail provides built-in CAN-SPAM compliance tooling so you never have to worry about regulatory requirements. When enabled (on by default), every outgoing email automatically includes:

1. List-Unsubscribe header — RFC 8058 compliant one-click unsubscribe
2. List-Unsubscribe-Post header — Required for one-click to work in Gmail, Apple Mail, etc.
3. Physical address footer — Your mailing address at the bottom of every email
4. Unsubscribe link — A visible link for recipients to opt out

Quick setup

curl -X PUT https://pushmail.dev/api/v1/compliance \
  -H "Authorization: Bearer pm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "physicalAddress": "123 Main Street\nSuite 100\nSan Francisco, CA 94105",
    "complianceEnabled": true
  }'

That's it. Every email you send will now include compliance headers and a footer with your address and an unsubscribe link.

How it works

Email headers

PushMail adds two headers to every outgoing email:

List-Unsubscribe: <https://pushmail.dev/api/v1/unsubscribe/TOKEN>, <https://pushmail.dev/api/v1/unsubscribe?token=TOKEN>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

These headers enable the "Unsubscribe" button that appears in Gmail, Apple Mail, Yahoo Mail, and other modern email clients. When a user clicks it, the email client sends a POST request to PushMail, and the contact is immediately unsubscribed.

Email footer

When you set a physical address, PushMail appends a footer to every email:

Your Organization Name
123 Main Street
Suite 100
San Francisco, CA 94105

Unsubscribe

The footer is inserted before the closing </body> tag (or appended to the end if no body tag exists).

Unsubscribe processing

When a contact unsubscribes (via header or link):

1. Contact status is set to unsubscribed
2. unsubscribedAt timestamp is recorded
3. Contact is added to the KV suppression list (365-day TTL)
4. All future sends to this contact are blocked

API endpoints

Get compliance settings

curl https://pushmail.dev/api/v1/compliance \
  -H "Authorization: Bearer pm_live_YOUR_KEY"

{
  "data": {
    "physicalAddress": "123 Main Street\nSuite 100\nSan Francisco, CA 94105",
    "unsubscribeUrl": null,
    "complianceEnabled": true,
    "orgName": "My Company"
  }
}

Update compliance settings

curl -X PUT https://pushmail.dev/api/v1/compliance \
  -H "Authorization: Bearer pm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "physicalAddress": "123 Main Street\nSuite 100\nSan Francisco, CA 94105",
    "unsubscribeUrl": "https://example.com/unsubscribe",
    "complianceEnabled": true
  }'

One-click unsubscribe (RFC 8058)

This endpoint is called by email clients when a user clicks the "Unsubscribe" button.

curl -X POST "https://pushmail.dev/api/v1/unsubscribe?token=UNSUB_TOKEN"

{
  "data": { "unsubscribed": true }
}

Browser unsubscribe

When a user clicks the unsubscribe link in the email footer, they see a confirmation page:

• GET /v1/unsubscribe/:token — Shows a confirmation page
• POST /v1/unsubscribe/:token — Processes the unsubscribe after confirmation

Custom unsubscribe URL

By default, PushMail hosts the unsubscribe page. If you want to handle unsubscribes on your own site:

1. Set a custom unsubscribeUrl in compliance settings
2. The custom URL will be used in email footers and List-Unsubscribe headers
3. You are responsible for calling the PushMail API to process the actual unsubscribe

curl -X PUT https://pushmail.dev/api/v1/compliance \
  -H "Authorization: Bearer pm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "unsubscribeUrl": "https://yoursite.com/email-preferences"
  }'

Disable compliance (not recommended)

You can disable automatic compliance insertion if you handle it yourself:

curl -X PUT https://pushmail.dev/api/v1/compliance \
  -H "Authorization: Bearer pm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "complianceEnabled": false }'

Dashboard

You can also manage compliance settings from the dashboard:

Settings > Compliance — Configure your physical address, custom unsubscribe URL, and toggle compliance on/off. Includes a live footer preview.

Next steps