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

# Deliverability

> Suppressions, bounces, complaints, and best practices

Getting into the inbox is a combination of infrastructure (DKIM, SPF, DMARC, IP reputation) and hygiene (clean lists, low complaint rates, honoring unsubscribes). Hiveku manages the infrastructure side. This page covers the hygiene side — suppressions, bounces, complaints, and the best practices that keep your sends landing.

## Suppression list

A **suppression** is an address Hiveku will not deliver to, even if you try to send. Suppressions exist to protect your reputation: repeatedly hitting addresses that bounce or complain is the fastest way to get your domain blocklisted.

### Auto-suppressions

Hiveku automatically adds an address to your suppression list when:

* A message to it **hard bounces** (mailbox does not exist, domain does not resolve, etc.)
* The recipient files a **complaint** (marks the message as spam via their mail client)

Auto-suppressions prevent sends to that address from that point forward. You still get a normal API response, but the message is dropped before ever reaching AWS SES.

### Manual suppressions

Add addresses manually when you have out-of-band signals you want to honor:

* A user unsubscribed from your own preference center
* A user emailed support asking to stop receiving mail
* You want to block internal test addresses from production sends

Manage manual suppressions via the dashboard or the API:

```ts theme={null}
await hiveku.suppressions.create({
  email: "customer@example.com",
  reason: "unsubscribed via preference center",
});
```

### Global suppression list

Hiveku also maintains a **global suppression list** shared across all customers — addresses that have repeatedly complained or bounced across the platform. You cannot override global suppressions. They protect platform-wide reputation.

## Bounces

Bounces fall into two categories:

* **Hard bounce** — Permanent failure (`550 User unknown`, invalid domain, mailbox full for days). Auto-suppressed.
* **Soft bounce** — Temporary failure (`421 Try again later`, mailbox full briefly, rate-limited by receiver). Retried automatically; not suppressed.

Target a **hard bounce rate below 5%**. Above 5%, receivers start throttling or blocking your mail, and Hiveku may pause sending from the affected domain.

## Complaints

Complaints arrive via **ARF (Abuse Reporting Format)** feedback loops that Hiveku maintains with major mailbox providers. Common complaint types:

* `abuse` — Recipient marked as spam
* `fraud` — Phishing or scam report
* `virus` — Mail flagged as malware
* `other` — Unspecified

Target a **complaint rate below 0.1%**. Above 0.3%, expect immediate deliverability degradation. Above 0.5%, expect blocks.

## View and manage suppressions

Go to **Settings > Email > Suppressions** to:

* Search for a specific address
* Filter by reason (hard bounce, complaint, manual)
* Export the list to CSV
* Remove an address (only for auto-suppressions you are certain have been resolved, e.g., you confirmed the mailbox is valid again)

<Warning>
  Only remove an auto-suppressed address if you have concrete evidence the underlying problem is fixed. Removing and resending to an address that still complains or bounces damages reputation faster than the original event did.
</Warning>

## Best practices

<AccordionGroup>
  <Accordion title="Always include an unsubscribe link in marketing email">
    Add both a visible unsubscribe link in the email body **and** the `List-Unsubscribe` and `List-Unsubscribe-Post` headers:

    ```ts theme={null}
    headers: {
      "List-Unsubscribe": "<https://acme.com/unsub?u=42>, <mailto:unsub@acme.com>",
      "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
    }
    ```

    This enables the "one-click unsubscribe" UI that Gmail and Apple Mail surface. Honor unsubscribes instantly — add the address to your suppression list.
  </Accordion>

  <Accordion title="Use double opt-in for subscribers">
    When a user subscribes, send a confirmation email with a verification link and require them to click it before their address is added to your list. Double opt-in keeps typos, bots, and hostile sign-ups off your list — the #1 source of spam-trap hits.
  </Accordion>

  <Accordion title="Monitor bounce and complaint rates">
    Target **\< 5% hard bounce** and **\< 0.1% complaint**. The domain reputation dashboard surfaces both. Set up `bounce` and `complaint` [webhooks](/email/webhooks) so you can react in real time — a spike almost always points to a list issue or a bad template.
  </Accordion>

  <Accordion title="Warm up new domains slowly">
    A brand-new domain has zero reputation. Start at **a few hundred sends per day** and ramp over 2-4 weeks. If you send from a [dedicated IP](/email/dedicated-ips), Hiveku handles IP warmup automatically, but domain warmup is still your responsibility.
  </Accordion>

  <Accordion title="Set up DMARC with a strict policy">
    Start with `p=quarantine` for a few weeks, review the aggregate reports sent to your `rua` address, then move to `p=reject` once you are confident all legitimate mail is aligned. A strict DMARC policy is now the de facto requirement for Gmail and Yahoo bulk sender compliance. See [Domains](/email/domains) for DMARC setup.
  </Accordion>

  <Accordion title="Always send from your own verified domain">
    Never use `@gmail.com`, `@yahoo.com`, or any other free mailbox provider as the `from` address. Their DMARC policies explicitly `reject` mail that is not sent from their servers. Use a verified subdomain you own, like `noreply@mail.acme.com`.
  </Accordion>
</AccordionGroup>

## Further reading

* [Domains](/email/domains) — DKIM, SPF, DMARC setup
* [Dedicated IPs](/email/dedicated-ips) — When to isolate your sending IP
* [Webhooks](/email/webhooks) — React to bounces and complaints in real time