> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Email Suppressions

> View and manage the list of emails that won't receive messages from you

Your suppression list is the set of addresses Hiveku won't send to — automatically populated by hard bounces and spam complaints, plus anything you add manually.

<Info>
  Hiveku adds addresses to your suppression list automatically whenever they hard-bounce or file a spam complaint. You don't need to do anything to keep the list healthy — but you can inspect, add, and remove entries via the API or AI chat.
</Info>

## Two Ways to Manage Suppressions

The dashboard suppression UI is read-only — you can view entries but not edit them there. For changes, use AI chat or the API.

<Tabs>
  <Tab title="AI Chat">
    The easiest way. In your project's AI tab, say what you want:

    ```
    Add customer@example.com to my email suppression list.
    ```

    Or:

    ```
    Remove customer@example.com from suppressions — they confirmed they want back on the list.
    ```

    The AI handles the API call for you and confirms the change.
  </Tab>

  <Tab title="API / SDK">
    Use the Hiveku email SDK (or raw HTTP).

    ```typescript theme={null}
    import { Hiveku } from '@hiveku-apps/email';

    const hiveku = new Hiveku({ apiKey: process.env.HIVEKU_EMAIL_KEY });

    // List suppressions
    const list = await hiveku.suppressions.list();

    // Add one
    await hiveku.suppressions.add({
      email: 'customer@example.com',
      reason: 'manual',
    });

    // Remove (after confirming they want back)
    await hiveku.suppressions.remove({
      email: 'customer@example.com',
    });
    ```

    Raw HTTP equivalent:

    ```bash theme={null}
    curl -X POST https://api.hiveku.com/v1/email/suppressions \
      -H "Authorization: Bearer $HIVEKU_EMAIL_KEY" \
      -H "Content-Type: application/json" \
      -d '{"email":"customer@example.com","reason":"manual"}'
    ```
  </Tab>
</Tabs>

## Suppression Reasons

Every entry has a reason that explains why it was added.

| Reason        | Source    | What it means                                                                |
| ------------- | --------- | ---------------------------------------------------------------------------- |
| `hard_bounce` | Automatic | Mail server permanently rejected the address (doesn't exist, domain invalid) |
| `complaint`   | Automatic | Recipient clicked "Spam" in their mail client                                |
| `manual`      | You       | You added it via API or AI chat                                              |

Hiveku doesn't auto-suppress **soft** bounces (mailbox full, temporary DNS failure). Those retry for a while, then suppress only after repeated failures.

## Global Suppression List

Hiveku maintains a platform-wide suppression list for addresses that have bounced or complained repeatedly across multiple customer accounts. This takes precedence over your account-level list.

If you try to unsuppress someone who's on the global list, your change succeeds at the account level but mail still won't send. The dashboard will show both states so you know which list is blocking delivery.

## Best Practices

<Tip>
  Wire your app's unsubscribe handler directly to the suppression API. When a user clicks unsubscribe, add their email as `reason: 'manual'`. That's faster and more reliable than managing a separate opt-out table.
</Tip>

* **Never remove a `hard_bounce` address blindly.** The mail server told you the address doesn't exist. Sending to it again damages your sender reputation.
* **Respect complaints.** If someone marked you as spam, do not put them back on your list — even if they later ask. In most jurisdictions (GDPR, CAN-SPAM, CASL), re-sending to a complainer is illegal.
* **Audit manual removals.** Keep a log of who removed what and why — auditors and your deliverability team will thank you.
* **Don't try to "clean" your list by sending to everyone first.** Use a list validation service (Kickbox, NeverBounce, ZeroBounce) before importing cold lists.

See the [deliverability reference](/email/deliverability) for more on list hygiene.

## Verify a Suppression

<Steps>
  <Step title="Add a test address">
    Use AI chat or the API to suppress a test email you control.
  </Step>

  <Step title="Try to send to it">
    Attempt a send via your normal flow. Hiveku silently filters the message — the API returns success but no email is delivered.
  </Step>

  <Step title="Check the logs">
    The email dashboard shows a `suppressed` status for that attempt, with the suppression reason.
  </Step>
</Steps>

## Find Your API Key

If you need an API key for suppression calls:

1. Go to **Settings > Email Service > API Keys**
2. Click **Create Key** if you don't have one
3. Copy it somewhere safe — Hiveku only shows it once

<Warning>
  API keys let a caller send email, manage suppressions, and read webhook configuration. Treat them like passwords — don't commit them, don't paste them in chat, and rotate if exposed.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Address is suppressed but I need to send to them">
    Check the reason. If it's `hard_bounce`, the address doesn't exist on the recipient's mail server — sending will bounce again. Verify the address is correct (typo? different domain?). If it's `complaint`, do not re-send — they marked you as spam, and sending again can get your domain blocklisted.
  </Accordion>

  <Accordion title="Unsuppression didn't work">
    The address is likely on the global suppression list, which overrides your account-level removals. Check the dashboard — if it shows `global_suppressed`, contact support to review.
  </Accordion>

  <Accordion title="Can't find my API key">
    Go to **Settings > Email Service > API Keys**. If the key you used was never saved, create a new one — Hiveku can't show the old key again.
  </Accordion>

  <Accordion title="Suppression list growing fast">
    A growth rate above 2% of sends is a warning sign. Audit your opt-in flow (are people actually consenting?), check for a broken form that submits garbage addresses, and validate cold lists before importing.
  </Accordion>

  <Accordion title="Suppressed myself by mistake">
    Use AI chat: *"Remove [my-email@example.com](mailto:my-email@example.com) from suppressions — it was added manually."* Then re-send your test.
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="Email Webhooks" icon="bolt" href="/how-tos/email-webhooks">
    React in real time when bounces and complaints happen
  </Card>

  <Card title="Deliverability Reference" icon="shield-check" href="/email/deliverability">
    Keep your sender reputation clean
  </Card>
</CardGroup>