Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
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

1
Inspect message state first, then attempts, logs, timeline, and bounces.
2
Use suppressions to identify recipients that StackShift will not queue mail to.
3
Create manual or blocked suppressions for recipients your application must not contact.
4
Check /mail/limits and /mail/reputation before raising volume.
5
Review 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

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

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.

Send email

Send a single outbound email with the official SDK or REST API, then inspect the message, attempts, logs, and timeline.

Events, webhooks, and timelines

List mail events, inspect per-message timelines, subscribe webhooks, rotate secrets, retry deliveries, and verify webhook signatures.

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.