Documentation

Bounces, suppressions, and reputation

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

Try StackShiftRead the overview

Search Docs

StackShift Mail

Bounces, suppressions, and reputation

Live

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

Goal

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

Current status

Live

This area is documented as current, user-reliable behavior.

Workflow

  1. 1Inspect message state first, then attempts, logs, timeline, and bounces.
  2. 2Use suppressions to identify recipients that StackShift will not queue mail to.
  3. 3Create manual or blocked suppressions for recipients your application must not contact.
  4. 4Check /mail/limits and /mail/reputation before raising volume.
  5. 5Review reputation events when status changes to watch, throttled, or disabled.

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

Example

ts
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

Example

ts
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

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

Common failures

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