Suppressions & Unsubscribe

Not everyone wants every email, and that's totally fine. Pigeon Perch gives your contacts the power to choose what they hear from you, and makes sure you respect those choices automatically.

How Suppressions Work

Global Unsubscribe

When someone globally unsubscribes, they're saying "I'm done, no more emails from you." Here's what happens:

• Their status flips to unsubscribed
• All future campaigns and automations skip them
• Any active automation enrollments get cancelled
• They won't hear from you again (unless they re-subscribe through the preferences page)

This happens when someone clicks the {{unsubscribe_url}} link, uses the native unsubscribe button in Gmail/Outlook, or checks "Unsubscribe from all" on the preferences page.

Group Suppression

This is the friendlier option. Instead of opting out entirely, your contact says "I like your newsletter, but stop sending me promotions."

You set up Suppression Groups (like "Newsletter", "Product Updates", "Listing Alerts"), and contacts can toggle each one on or off.

When someone is suppressed from a group:

• Campaigns and automations tagged with that group will skip them
• They still get emails from other groups
• Their contact status stays subscribed

Bounces & Complaints

These happen automatically. You don't have to think about them.

• Bounced: the email address doesn't exist or the mailbox is full. We stop trying.
• Complained: someone hit "Report Spam." We take them off the list permanently.

Setting Up Suppression Groups

1. Create Your Groups

Go to Settings → Suppression Groups in your dashboard. You can also use the API (POST /api/v1/suppression-groups).

Each group needs a name and a description. Your contacts will see both of these on the preferences page, so write them like you're talking to a person, not a database:

Some ideas to get you started:

• Newsletter: your regular editorial sends
• Product Updates: new features, releases, announcements
• Listing Alerts: new listings or price drops (great for real estate and e-commerce)
• Promotions: sales, discounts, limited-time offers

2. Tag Your Campaigns & Automations

When you create or edit a campaign or automation, you'll see a Suppression Group dropdown. Pick the group that matches what kind of email this is.

At send time, anyone who opted out of that group gets skipped automatically. Contacts who are globally unsubscribed, bounced, or complained are always skipped too.

If you don't assign a suppression group, the email goes to all subscribed contacts (only global unsubscribes are filtered).

3. Add Unsubscribe Links to Your Emails

Drop these template variables into your email footer:

On top of that, every email includes List-Unsubscribe headers so Gmail, Apple Mail, and Outlook show a native unsubscribe button. That happens automatically.

What Your Contacts See

The Unsubscribe Page

When someone clicks {{unsubscribe_url}}, they land on a simple page that confirms they've been unsubscribed from everything. There's also a link that says "Changed your mind? Manage your preferences instead" in case they acted too fast.

The Preferences Page

When someone clicks {{preferences_url}}, they see a clean page with:

• Your organization name at the top
• Their email address
• A checkbox for each suppression group (checked = subscribed, unchecked = opted out)
• An "Unsubscribe from all" checkbox at the bottom
• A save button

They can opt out of specific groups while staying on others. If they were globally unsubscribed and come back to this page to re-subscribe to something, we'll flip their status back to subscribed. Everyone gets a second chance.

Re-subscribing

If someone globally unsubscribed but later visits the preferences page and saves without "Unsubscribe from all" checked, they're back in. Their status returns to subscribed and their group preferences are saved.

This matters for compliance. CAN-SPAM and GDPR both say you need to give people a clear way to manage their preferences, including coming back if they want to.

API

You can manage suppression groups programmatically too:

All endpoints need a Bearer token or API key. See API docs for the full rundown.

Good Habits

• Set up groups before your first send. That way contacts can manage preferences from day one.
• Tag every campaign with a group. If you skip this, the only thing protecting people is global unsubscribe. Group suppressions won't apply.
• Name groups for humans. "Weekly Newsletter" beats "Group A." Your contacts read these names.
• Keep it to 3-5 groups. Too many choices and people just hit "unsubscribe from all."
• Always include the preferences link. It's the difference between losing a subscriber and just losing one category.