> ## 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.

# Suppression List

> The addresses the Email Service will not send to, and how to see, add, remove and import them

Your suppression list is the set of addresses Hiveku will not send to. Hiveku adds hard bounces and spam complaints to it for you, and you can add your own or import the list of the email service you used before.

> [!NOTE]
>
> Hiveku adds an address automatically when an email to it hard-bounces or its owner marks your email as spam. You don't need to do anything to keep the list healthy, but you can look at it, add to it, and take off addresses that may be taken off.

## The Suppression list page

Go to **Settings > Email Service > Suppression list**. It lists every address on your list, newest first, with:

* **Why** it is there, in plain words: Bounced, Marked as spam, Could not be sent, Do Not Contact or added by your team, Unsubscribed, or Another reason. Under it, the note stored with the address, such as "Imported from Mailgun".
* **First added**: the date the address first went on the list. An address taken off and put back keeps that date.
* **Take off**, on an address that may be taken off. **Kept on for good** on an address that can never be taken off, such as a hard bounce or a spam complaint. **Do Not Contact** on an address marked Do Not Contact on a contact in the CRM, with a link to that contact.

Find an address with the search box, or show one reason at a time.

Everyone on your team can see the list. Adding, taking off and importing need **Email Service: Manage**: owners and admins, or a role given it.

### Add an address

Click **Add address**, enter the address, choose why (**Added by your team** or **Unsubscribed**), add a note if you like, and click **Add to the list**. An address already on the list is left as it is. An address you add can be taken off again later.

### Take an address off

Click **Take off** next to it and confirm. Email from your account can go to that address again: campaigns, sequences, invoices and app email. An unsubscribe the person made from your campaigns or sequences still holds. An address that can never be taken off, such as a hard bounce or a spam complaint, shows **Kept on for good** instead.

An address marked Do Not Contact on a contact shows **Do Not Contact** instead. Click **Allow contact again on the contact's page** under it, then **Allow contact again** on the contact. That lifts it everywhere at once: email, CRM sequences, and texts unless the person texted STOP.

### Import a list from another email service

Moving from Resend, Mailgun or another email service? Bring its suppression list over, so the people who bounced, complained or unsubscribed there are not emailed from Hiveku.

**1. Export the list from your old service**

Download its suppression list as a CSV file: bounces, spam complaints and unsubscribes. Some services export each list as its own file. Import each one.

**2. Open the import**

On **Settings > Email Service > Suppression list**, click **Import CSV**, and choose the service you are moving from. Its name goes in the note of each address, such as "Imported from Resend".

**3. Say what the rows are**

Choose what to call the rows the file does not mark as bounced, spam or unsubscribed: **Added by your team**, **Unsubscribed**, **Bounced** or **Marked as spam**. A file with a column that says each row's type, such as Resend's `origin`, keeps each row's own type.

**4. Choose the file**

The page finds the column of addresses (named `email` or `address`, or one address on each line) and says how many rows it read and which columns it uses.

**5. Check the file**

Click **Check the file**. Each row's result is listed, and nothing changes yet: **Will be added**, **Will be put back on the list** (an address taken off before), **Will be kept on for good** (an address that may be taken off now, which the file calls a bounce or a spam complaint), **Already on the list**, or **Skipped**, with why: not one email address, or listed earlier in the file.

**6. Import**

Click the **Import** button, which says how many addresses it will add or change. When some are bounces or spam complaints, Hiveku asks first: those stay on the list for good. Each row's result is listed again, as it was done.

> [!WARNING]
>
> Bounces and spam complaints you import stay on the list for good: nobody can take them off later, on the page, through the API or through your AI assistant. Import only addresses your old service marked that way.

A file can hold up to 5,000 addresses and 5 MB. Split a longer list into several files. Save the file as CSV, with commas between columns. Importing the same file twice is safe: addresses already on the list are left as they are.

## Other ways to manage suppressions

**AI assistant**

Ask your AI assistant what you want:

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

Or:

```
Remove customer@example.com from my email suppressions. They asked to get our email again.
```

It can list, add and remove suppressions. It refuses to remove a hard bounce or a spam complaint.

**API**

```bash theme={null}
# List them (any key)
curl "https://app.hiveku.com/api/v1/email/suppressions?type=manual" \
  -H "Authorization: Bearer $HIVEKU_EMAIL_API_KEY"

# Add one
curl -X POST https://app.hiveku.com/api/v1/email/suppressions \
  -H "Authorization: Bearer $HIVEKU_SUPPRESSIONS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "customer@example.com", "reason": "Unsubscribed in our app" }'

# Remove one you added
curl -X DELETE "https://app.hiveku.com/api/v1/email/suppressions?email=customer@example.com" \
  -H "Authorization: Bearer $HIVEKU_SUPPRESSIONS_KEY"
```

Listing works with any key. Adding and removing need a key with the `email:suppressions` permission: tick **Manage Suppressions** when you create the key, or on its page under **Settings > API Keys**. Adding an address that was taken off puts it back on the list (`201`, with `resurrected: true`); an address on the list now answers `409 already_exists`. The Node.js SDK has no suppression methods.

**CRM**

Open the contact in the CRM and click **Mark as Do Not Contact**. Hiveku then stops emailing that address across your account, from invoices and bookings to the email API, except replies to their own support tickets. **Allow contact again** on the contact lifts it. The Suppression list page shows such an address as **Do Not Contact**, with a link to the contact.

## Suppression types

Every entry has a type that says why it is there. The page shows it in words.

| Type | On the page | Added by | What it means | Can be removed |
| - | - | - | - | - |
| `bounce` | Bounced | Hiveku, or an import | A hard bounce: the mailbox or the domain does not exist | No, if recorded since 12 September 2026, or imported |
| `complaint` | Marked as spam | Hiveku, or an import | The recipient marked your email as spam | No, if recorded since 12 September 2026, or imported |
| `manual` | Do Not Contact or added by your team | You | Added on the page, through the API, by your AI assistant, by an import, or Do Not Contact in the CRM | Yes. Do Not Contact is lifted on the contact |
| `unsubscribe` | Unsubscribed | You | Added on the page, by an import, or by your AI assistant | Yes |

Your AI assistant can also record other types. The page shows them as **Another reason**.

Hiveku does not suppress **soft** bounces, such as a full mailbox or a passing DNS failure.

## Best practices

> [!TIP]
>
> Wire your app's unsubscribe handler to the suppression API. When someone unsubscribes, add their address. That is faster and safer than keeping a separate opt-out table.

* **Leave bounces alone.** The mail server said the address does not exist. Hiveku keeps it suppressed for you.
* **Respect complaints.** Someone who marked you as spam stays suppressed. Do not try to mail them from another account or domain.
* **Note why you remove an address.** Keep your own record of who was taken off the list and why.
* **Bring your old list with you.** When you move from another email service, import its suppression list before your app sends from Hiveku.
* **Don't clean a list by sending to it.** Check a cold list with a list validation service before you import it.

See [Deliverability](https://docs.hiveku.com/email/deliverability.md) for more on list hygiene.

## Check a suppression

**1. Add a test address**

Suppress an address you control, on the Suppression list page, through your AI assistant, or through the API.

**2. Send to it**

Send an email to it and to one other address through the REST API. The answer lists the test address in `suppressed_recipients`, and the email goes to the other one only.

**3. Send to it alone**

With the test address as the only recipient, the REST API refuses the email with `400 all_recipients_suppressed`, and nothing is sent.

## Troubleshooting

> **An address is suppressed but I need to send to it**
>
> Check why on the Suppression list page. **Bounced** means the address does not exist on the recipient's mail server: check for a typo or a different domain. **Marked as spam** means the person marked you as spam: do not send to them again. Neither can be taken off if it was recorded since 12 September 2026, or imported.

> **There is no Take off button on an address**
>
> The address shows **Kept on for good**: a bounce or a spam complaint that cannot be taken off. Or it shows **Do Not Contact**: open the contact from the link under it and click **Allow contact again**. If you see no buttons at all, your role cannot change the list: an owner or admin can, or can give your role **Email Service: Manage**.

> **Adding a suppression through the API answers 403**
>
> The key lacks the `email:suppressions` permission. Tick **Manage Suppressions** on the key's page under **Settings > API Keys**, or add the address on the Suppression list page.

> **Rows of my import were skipped**
>
> Each skipped row says why: not one email address (an empty cell, a name, or two addresses in one cell), or listed earlier in the file, where it is counted once. Fix the rows and import the file again: addresses already on the list are left as they are.

> **The suppression list is growing fast**
>
> A fast-growing list is a warning sign. Check your opt-in flow (are people really agreeing?), look for a broken form that submits made-up addresses, and check cold lists before you import them.

> **I suppressed myself by mistake**
>
> Click **Take off** next to your address on the Suppression list page, or ask your AI assistant: *"Remove [my-email@example.com](mailto:my-email@example.com) from my email suppressions. I added it by mistake."* Then send your test again.

## What's next?

> **[Email Webhooks](https://docs.hiveku.com/how-tos/email-webhooks.md)**
>
> React as bounces and complaints happen

> **[Deliverability Reference](https://docs.hiveku.com/email/deliverability.md)**
>
> Keep your sender reputation clean


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.