Skip to content

This term

Suppression List

A do-not-message list of opted-out, blocked, invalid or legally restricted numbers that every outbound send is checked against before it goes out.

Also called: Do-not-message list · Do-not-contact list · Opt-out list · Exclusion list

Often confused with

Opt-out

A customer's request to stop WhatsApp messages from a business, by keyword, button, WhatsApp's own controls or a block, which must be honoured at once.

Read the Opt-out entry

Send or suppress? Route each contact

10 / 10

Only agents with the required skill are eligible; the least busy of them wins.

Incoming · 0 left

  1. All 10 conversations have been routed.

Conversation 10 of 10 · Skills-based

Vikram · +91 98860…(needs clear)goes toSend

Skills: needs clear, and only Send has it.

  • Send

    4 of 4 open

    Full
    • clear
    1. Kavya · +91 98450…needs clear
    2. Neha · +91 99000…needs clear
    3. Pooja · +91 97400…needs clear
    4. Vikram · +91 98860…needs clear

  • Marketing opt-out

    2 of 2 open

    Full
    • opted-out
    1. Imran · replied STOPneeds opted-out
    2. Rohit · opt-out buttonneeds opted-out

  • Stopped in WhatsApp

    2 of 2 open

    Full
    • 131050
    1. Arjun · stopped marketingneeds 131050
    2. Sana · stopped in appneeds 131050

  • Undeliverable

    1 of 1 open

    Full
    • invalid
    1. Old lead · 3× undeliverableneeds invalid

  • Erased (hash only)

    1 of 1 open

    Full
    • erased
    1. Re-imported · erasedneeds erased

Waiting · 0

  1. Nobody waiting: every conversation found an agent.
Same 10 conversations, each strategy
StrategyRoutedWaitingSkill mismatches
Skills-based1000
Round-robin1005
Ten contacts from a campaign audience, each tagged with its status. With the list enforced, every contact lands in the right lane; switch to round-robin to see what a sender that ignores the list does.

Conversation 10 of 10, Vikram · +91 98860…: Skills: needs clear, and only Send has it.

What is a suppression list?

A suppression list is a business's register of phone numbers (or business-scoped user IDs) that must not receive some or all of its WhatsApp messages. Before any outbound send — a Broadcast, a journey step, a CRM-triggered template — the recipient is checked against the list, and a match stops the message. It is the enforcement half of consent: an Opt-out is what the customer does, and the suppression list is how every system you run remembers it.

Entries come from several sources: STOP replies and opt-out buttons; the User Preferences Webhook, which reports people who stopped your marketing inside WhatsApp (marketing to them then fails with error 131050); numbers that keep failing as undeliverable; people who exercised the Right to Erasure; and legal or policy restrictions, such as children without verified parental consent or +1 US numbers, to which WhatsApp does not deliver marketing.

A good suppression list is scoped and reasoned. Each entry records the number in E.164 form, the scope (all messages, marketing only, one brand or product line), the reason, the source and the time, so a customer who declines promotions still receives the OTP and delivery update they asked for. It differs from the Block Users API, which blocks an abusive user on WhatsApp itself, and from Frequency Capping, which limits how often people who have consented hear from you.

Key takeaways

  • A suppression list is the do-not-message register every outbound send is checked against, whichever tool sends it.
  • It holds opt-outs, users who stopped your marketing inside WhatsApp (error 131050), invalid numbers, erased contacts and legal restrictions.
  • An opt-out is the customer's action; the suppression list is the system that makes every sending tool honour it.
  • Scope each entry: a marketing stop blocks campaigns, not the OTPs and order updates the customer still needs.
  • Check at send time as well as when the audience is built, so an opt-out received an hour ago still wins.

Why the difference matters

Why does a suppression list matter?

Most opt-out failures are not bad intent but plumbing: the STOP landed in the helpdesk while the campaign tool used last month's CSV. Each message to someone who said stop invites a block or a report, which pushes up your Block Rate and drags down quality, and it breaks Meta's rule to respect every opt-out request, on or off WhatsApp. One suppression service that every sender must call turns consent from a per-tool setting into a single source of truth — and it saves money, because messages to numbers that will never deliver or never convert are pure cost.

How does a suppression list work?

  1. Step 1

    Collect every source

    Feed the list from STOP keywords, opt-out buttons, user_preferences stop events, agent notes, email and web unsubscribes, erasure requests and legal holds. Normalise every number to E.164 before storing it.

  2. Step 2

    Store scope and reason

    Record a scope (all, marketing, a brand), the reason, the source and a timestamp. A marketing stop must not silence order updates; an erasure or legal hold silences everything.

  3. Step 3

    Check at send time

    Filter the audience when a campaign is built and again in the sending worker just before each API call, so opt-outs that arrive between scheduling and sending still win.

  4. Step 4

    Learn from failures

    Add numbers that fail with 131050 at once. Count 131026 (message undeliverable) failures and suppress after a few, with an expiry so the number is rechecked later. Never suppress on 131049.

  5. Step 5

    Lift entries only on fresh consent

    Remove a marketing entry only on a new, recorded opt-in or a user_preferences resume event, and keep the full history in the Consent Record.

A suppression list in code

// Every sender calls this: broadcasts, journeys, CRM triggers, agents
export async function canSend(waId, category) {
  const { rows } = await db.query(
    `SELECT scope FROM suppression
      WHERE wa_id = $1 AND (expires_at IS NULL OR expires_at > now())`,
    [waId],
  );
  // 'all' blocks everything; 'marketing' blocks marketing templates only
  return !rows.some((r) => r.scope === "all" || r.scope === category);
}
 
export async function sendTemplate(waId, template) {
  if (!(await canSend(waId, template.category))) {
    await log.skip(waId, template.name, "suppressed");
    return { skipped: true };
  }
  const res = await fetch(
    `https://graph.facebook.com/v26.0/${process.env.PHONE_NUMBER_ID}/messages`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.ACCESS_TOKEN}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        messaging_product: "whatsapp",
        to: waId,
        type: "template",
        template: { name: template.name, language: { code: template.lang } },
      }),
    },
  );
  return res.json();
}

Check in the worker that makes the API call, not only when the audience is built.

Common mix-ups

Common mistakes with a suppression list

  • One list per tool

    If the broadcast tool, the CRM and the helpdesk each keep their own list, an opt-out reaches one of them. Run one suppression service that every sender must call.

  • Suppressing everything for a marketing stop

    Blocking OTPs and order updates for a customer who only declined promotions hurts them and your support team. Scope entries by message category.

  • Suppressing on 131049

    The per-user marketing limit is temporary and set by Meta across all businesses. Retry after at least 24 hours instead of treating the person as opted out.

  • Checking only when the list is built

    A campaign built at 9 and sent at 11 misses the opt-outs from the two hours in between. Check again in the sending worker.

  • Mismatched number formats

    09812345678, +91 98123 45678 and 919812345678 are one person. Normalise to E.164 on the way in, or lookups will miss.

Example: A Jaipur spice brand's festive send

A Jaipur spice brand sends WhatsApp messages from three tools: a broadcast tool, a cart-recovery app and a helpdesk. Before Diwali, its 42,000-contact audience is filtered through one suppression service: 1,180 marketing opt-outs from STOP replies and the opt-out button, 310 people who stopped its marketing inside WhatsApp, 95 numbers that failed as undeliverable three times, and 12 erased contacts held only as keyed hashes. On send day a customer replies STOP to an order update at 10:02; the 10:30 campaign worker checks the list again and skips her. Her delivery updates, sent as utility templates, keep arriving, because her entry is scoped to marketing only.

A suppression list: key facts and limits

Typical scopes
All messages · marketing only · one brand or product line
Stopped marketing in WhatsApp
Error 131050 — suppress, never retry
Per-user marketing limit
Error 131049 — retry after 24 hours, do not suppress
Undeliverable
Error 131026 — suppress after repeated failures, with an expiry
Key format
E.164 digits (wa_id); keyed hash for erased contacts
When to check
At audience build and again just before each API call

Suppression List FAQs

What is the difference between an opt-out and a suppression list?+
An opt-out is the customer's request to stop; the suppression list is the system that enforces it. One opt-out should create one entry that every sending tool checks before it sends.
Should I remove someone from my suppression list if they message me again?+
Not for marketing. A new inbound message lets you reply inside the customer service window, but it is not a new marketing opt-in; lift the entry only on fresh, recorded consent.
Does WhatsApp keep its own suppression list for my business?+
Partly. When a person stops your marketing inside WhatsApp, Meta stops delivering it and sends fail with error 131050, but STOP replies in chat and opt-outs given elsewhere are yours to record and enforce.
How long should numbers stay on a suppression list?+
Opt-outs and erasure entries stay until fresh consent; they should not expire on their own. Undeliverable numbers can carry an expiry, such as 30 to 90 days, so they are rechecked.

Rules of thumb

Best practices for a suppression list

  • Make suppression a service with one API, not a spreadsheet exported weekly.
  • Log every skipped send with its reason, so an audit can show the list working.
  • Recheck expiring undeliverable entries instead of keeping them forever.
  • Show agents a contact's suppression scope in the inbox before they send a template.

See InfiQ pricing

Try it on the official WhatsApp Business API

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms