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

# Bounces, suppressions, and reputation

> Handle hard and soft bounces, workspace-scoped suppressions, sending limits, warmup stage, domain reputation, and reputation events.

<Tip>
  **Live.** This area is documented as current, user-reliable behavior.
</Tip>

## Goal

Operate Mail volume without repeatedly sending to addresses or domains that should be blocked or throttled.

## Prerequisites

* Mail sending enabled in the workspace
* Message IDs or recipient emails when investigating a delivery issue

## Workflow

<Steps>
  <Step>
    Inspect message state first, then attempts, logs, timeline, and bounces.
  </Step>

  <Step>
    Use suppressions to identify recipients that StackShift will not queue mail to.
  </Step>

  <Step>
    Create manual or blocked suppressions for recipients your application must not contact.
  </Step>

  <Step>
    Check /mail/limits and /mail/reputation before raising volume.
  </Step>

  <Step>
    Review reputation events when status changes to watch, throttled, or disabled.
  </Step>
</Steps>

## Bounce and suppression facts

* Bounce type is hard, soft, or unknown.
* Bounce source can be DSN, SMTP log, manual, or internal in the server domain model.
* Suppression reasons are hard\_bounce, complaint, manual, repeated\_soft\_bounce, blocked, and unsubscribe.
* Suppression sources are bounce\_processor, user, system, and future\_complaint\_processor.
* Hard bounces are automatically suppressed by the backend.
* Suppressions are workspace-scoped and checked before a message is queued.

## Suppress a recipient manually

```ts theme={null}
const suppression = await stackshift.mail.suppressions.create({
  email: 'bad@example.net',
  reason: 'blocked',
  metadata: { source: 'admin_review' },
})

const current = await stackshift.mail.suppressions.list({
  email: 'bad@example.net',
})

console.log(suppression.id, current.data)
```

## Inspect limits and reputation

```ts theme={null}
const limits = await stackshift.mail.limits.get()
const reputation = await stackshift.mail.reputation.get()
const events = await stackshift.mail.reputation.events.list({
  severity: 'warning',
  limit: 20,
})

console.log(limits.tier, limits.dailyUsed, limits.dailyLimit)
console.log(reputation.workspace.status, reputation.workspace.score)
console.log(events.data)
```

## Reputation fields

* Workspace and domain status is healthy, watch, throttled, or disabled.
* Tier is sandbox, starter, verified, trusted, or custom.
* Limits include dailyLimit, dailyUsed, hourlyLimit, hourlyUsed, perMinuteLimit, currentWarmupStage, and manualReviewStatus.
* Reputation metrics include score, bounceRate, deferralRate, suppressionRate, and complaintRate where available.
* Reputation events include id, type, severity, message, metadata, and createdAt.

## Expected result

<Check>
  High-risk recipients are suppressed, hard bounces stop repeat sends, and operators can see current usage limits and reputation posture.
</Check>

## Common failures

<Warning>
  * Treating sent as final mailbox delivery instead of MTA acceptance.
  * Retrying suppressed recipients without deleting or resolving the suppression.
  * Ignoring reputation events when bounce or deferral rates rise.
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Send email" href="/stackshift-mail/send-email">
    Send a single outbound email with the official SDK or REST API, then inspect the message, attempts, logs, and timeline.
  </Card>

  <Card title="Events, webhooks, and timelines" href="/stackshift-mail/events-webhooks-and-timelines">
    List mail events, inspect per-message timelines, subscribe webhooks, rotate secrets, retry deliveries, and verify webhook signatures.
  </Card>

  <Card title="Sender domains and DNS" href="/stackshift-mail/sender-domains-and-dns">
    Create and verify outbound sender domains, inspect SPF, DKIM, DMARC, and return-path record status, and know what the domain status fields mean.
  </Card>
</CardGroup>