Suppression Management

Suppressions prevent emails from being sent to addresses that have bounced, complained, or requested removal. Managing suppressions properly is critical for maintaining good deliverability.

Why Suppressions Matter

Sending to invalid or unwilling recipients damages your sender reputation:

Hard bounces: Permanent delivery failures (email address doesn’t exist, domain invalid, recipient rejected)
Soft bounces: Temporary delivery failures (mailbox full, server temporarily unavailable)
Complaints: Recipients who mark your email as spam
Unsubscribes: Users who opted out

Email providers track these signals. Too many bounces or complaints can land your emails in spam folders or get your domain blocklisted.

Automatic Suppressions

Ark automatically adds email addresses to your suppression list to protect your sender reputation:

Event	Action	Reason in API
Hard bounce	Immediately suppressed on first occurrence	`hard fail`
Soft bounce exhausted	Suppressed after 18 failed retry attempts (~48 hours)	`too many soft fails`
Spam complaint	Immediately suppressed	`complaint`
Unsubscribe click	Immediately suppressed	`unsubscribe`

Hard bounces trigger immediate suppression. Unlike some email providers that wait for multiple failures, Ark adds recipients to the suppression list on the very first hard bounce. This aggressive approach protects your sender reputation by preventing repeated delivery attempts to invalid addresses.

Viewing Suppressions

List All Suppressions

Python
Node.js
Ruby
Go
cURL

from ark import Ark

client = Ark()

suppressions = client.suppressions.list()

for s in suppressions.data:
    print(f"{s.email}: {s.reason} (added {s.created_at})")

print(f"Total suppressed: {len(suppressions.data)}")

import Ark from 'ark';

const client = new Ark();

const suppressions = await client.suppressions.list();

for (const s of suppressions.data) {
  console.log(`${s.email}: ${s.reason} (added ${s.createdAt})`);
}

console.log(`Total suppressed: ${suppressions.data.length}`);

require "ark_email"

client = ArkEmail::Client.new

suppressions = client.suppressions.list

suppressions.data.each do |s|
  puts "#{s.email}: #{s.reason} (added #{s.created_at})"
end

puts "Total suppressed: #{suppressions.data.length}"

client := ark.NewClient()

suppressions, _ := client.Suppressions.List(ctx, ark.SuppressionListParams{})

for _, s := range suppressions.Data {
    fmt.Printf("%s: %s (added %s)\n", s.Email, s.Reason, s.CreatedAt)
}

fmt.Printf("Total suppressed: %d\n", len(suppressions.Data))

curl "https://api.arkhq.io/v1/suppressions" \
  -H "Authorization: Bearer $ARK_API_KEY"

Filter by Reason

Python
Node.js
Ruby
cURL

# View only bounces
bounces = client.suppressions.list(reason="hard_bounce")

# View only complaints
complaints = client.suppressions.list(reason="complaint")

// View only bounces
const bounces = await client.suppressions.list({ reason: 'hard_bounce' });

// View only complaints
const complaints = await client.suppressions.list({ reason: 'complaint' });

# View only bounces
bounces = client.suppressions.list(reason: "hard_bounce")

# View only complaints
complaints = client.suppressions.list(reason: "complaint")

# View only bounces
curl "https://api.arkhq.io/v1/suppressions?reason=hard_bounce" \
  -H "Authorization: Bearer $ARK_API_KEY"

# View only complaints
curl "https://api.arkhq.io/v1/suppressions?reason=complaint" \
  -H "Authorization: Bearer $ARK_API_KEY"

Check Specific Email

Before sending, check if an email is suppressed:

Python
Node.js
Ruby
Go

import ark

def is_email_suppressed(email):
    try:
        suppression = client.suppressions.retrieve(email)
        return True, suppression.data.reason
    except ark.NotFoundError:
        return False, None

# Usage
suppressed, reason = is_email_suppressed("[email protected]")
if suppressed:
    print(f"Email is suppressed: {reason}")
else:
    # Safe to send
    client.emails.send(...)

import Ark from 'ark';

async function isEmailSuppressed(email: string) {
  try {
    const suppression = await client.suppressions.retrieve(email);
    return { suppressed: true, reason: suppression.data.reason };
  } catch (error) {
    if (error instanceof Ark.NotFoundError) {
      return { suppressed: false, reason: null };
    }
    throw error;
  }
}

// Usage
const { suppressed, reason } = await isEmailSuppressed('[email protected]');
if (suppressed) {
  console.log(`Email is suppressed: ${reason}`);
} else {
  // Safe to send
  await client.emails.send({...});
}

def email_suppressed?(email)
  suppression = client.suppressions.retrieve(email)
  [true, suppression.data.reason]
rescue ArkEmail::Errors::NotFoundError
  [false, nil]
end

# Usage
suppressed, reason = email_suppressed?("[email protected]")
if suppressed
  puts "Email is suppressed: #{reason}"
else
  # Safe to send
  client.emails.send_(...)
end

func isEmailSuppressed(ctx context.Context, client *ark.Client, email string) (bool, string) {
    suppression, err := client.Suppressions.Get(ctx, email)
    if err != nil {
        var arkErr *ark.Error
        if errors.As(err, &arkErr) && arkErr.StatusCode == 404 {
            return false, ""
        }
        log.Fatal(err)
    }
    return true, suppression.Data.Reason
}

// Usage
suppressed, reason := isEmailSuppressed(ctx, client, "[email protected]")
if suppressed {
    fmt.Printf("Email is suppressed: %s\n", reason)
} else {
    // Safe to send
    client.Emails.Send(ctx, params)
}

Manual Suppression

Add emails manually (e.g., user requested removal):

Python
Node.js
Ruby
Go

client.suppressions.create(
    email="[email protected]",
    reason="user_requested"
)

await client.suppressions.create({
  email: '[email protected]',
  reason: 'user_requested',
});

client.suppressions.create(
  email: "[email protected]",
  reason: "user_requested"
)

client.Suppressions.Create(ctx, ark.SuppressionCreateParams{
    Email:  ark.String("[email protected]"),
    Reason: ark.String("user_requested"),
})

Bulk Add Suppressions

Python
Node.js
Ruby
Go

result = client.suppressions.bulk_create(
    suppressions=[
        {"email": "[email protected]", "reason": "hard_bounce"},
        {"email": "[email protected]", "reason": "complaint"},
    ]
)

print(f"Added {result.data.created_count} suppressions")

const result = await client.suppressions.bulkCreate({
  suppressions: [
    { email: '[email protected]', reason: 'hard_bounce' },
    { email: '[email protected]', reason: 'complaint' },
  ],
});

console.log(`Added ${result.data.createdCount} suppressions`);

result = client.suppressions.bulk_create(
  suppressions: [
    { email: "[email protected]", reason: "hard_bounce" },
    { email: "[email protected]", reason: "complaint" }
  ]
)

puts "Added #{result.data.created_count} suppressions"

result, _ := client.Suppressions.BulkCreate(ctx, ark.SuppressionBulkCreateParams{
    Suppressions: []ark.SuppressionInput{
        {Email: ark.String("[email protected]"), Reason: ark.String("hard_bounce")},
        {Email: ark.String("[email protected]"), Reason: ark.String("complaint")},
    },
})

fmt.Printf("Added %d suppressions\n", result.Data.CreatedCount)

Removing Suppressions

Use caution. Removing a suppression for a hard-bounced email will likely result in another bounce, harming your reputation.

Only remove suppressions when:

The email was incorrectly added
A user confirms their email is now valid
You’ve verified the issue is resolved

Python
Node.js
Ruby
Go

client.suppressions.delete("[email protected]")
print("Removed from suppression list")

await client.suppressions.delete('[email protected]');
console.log('Removed from suppression list');

client.suppressions.delete("[email protected]")
puts "Removed from suppression list"

client.Suppressions.Delete(ctx, "[email protected]")
fmt.Println("Removed from suppression list")

Sync with Your Database

Use webhooks to keep your database in sync:

Node.js
Python

app.post('/webhooks/ark', async (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'MessageBounced':
      await db.users.update({
        where: { email: event.data.to },
        data: {
          emailValid: false,
          emailInvalidReason: 'bounce',
          bounceType: event.data.bounceType,
        },
      });
      break;

    case 'MessageComplained':
      await db.users.update({
        where: { email: event.data.to },
        data: {
          emailValid: false,
          emailInvalidReason: 'complaint',
          optedOut: true,
        },
      });
      break;
  }

  res.status(200).send('OK');
});

@app.post("/webhooks/ark")
async def handle_webhook(request: Request):
    event = await request.json()

    if event["type"] == "MessageBounced":
        await db.users.update(
            email=event["data"]["to"],
            email_valid=False,
            email_invalid_reason="bounce",
            bounce_type=event["data"]["bounceType"]
        )
    elif event["type"] == "MessageComplained":
        await db.users.update(
            email=event["data"]["to"],
            email_valid=False,
            email_invalid_reason="complaint",
            opted_out=True
        )

    return {"status": "ok"}

Understanding Bounce Types

Bounces indicate that an email could not be delivered. Understanding the difference between bounce types is crucial for managing your email program effectively.

Hard Bounces (Permanent Failures)

A hard bounce is a permanent delivery failure. The email will never be deliverable to this address. Common causes:

Email address doesn’t exist (user unknown, mailbox not found)
Domain doesn’t exist or has no mail servers
Recipient server permanently rejected the message
Email address was disabled or deleted

Ark’s behavior: Immediately adds the recipient to the suppression list on the first hard bounce. No retries are attempted. SMTP codes: Typically 5xx errors (500-599)

{
  "status": "HardFail",
  "details": "550 5.1.1 The email account that you tried to reach does not exist",
  "suppression_added": true,
  "suppression_reason": "hard fail"
}

Soft Bounces (Temporary Failures)

A soft bounce is a temporary delivery failure. The email might be deliverable if retried later. Common causes:

Mailbox full (quota exceeded)
Server temporarily unavailable
Message too large
Connection timeout
Greylisting (intentional delay by receiving server)

Ark’s behavior:

Retries delivery with exponential backoff
Makes up to 18 retry attempts over approximately 48 hours
If all retries fail, converts to hard fail and adds to suppression list

SMTP codes: Typically 4xx errors (400-499)

{
  "status": "SoftFail",
  "details": "452 4.2.2 Mailbox full",
  "retry_after": "2024-01-15T10:05:00Z",
  "attempts": 3,
  "max_attempts": 18
}

Bounce vs Hard Fail

Term	Meaning	Automatic Suppression
HardFail	Permanent delivery failure at send time (SMTP 5xx)	Yes - reason `hard fail`
Bounced	NDR received after initial acceptance	No - handle via webhook
SoftFail	Temporary failure (SMTP 4xx), will retry	No - retries up to 18 times

Important distinction: Only HardFail status triggers automatic suppression. The Bounced status (from NDR messages) does NOT automatically add to the suppression list. You should handle the MessageBounced webhook and manually suppress via the API if desired.

Suppression Expiration

Suppressions automatically expire after 30 days by default. This allows addresses to become deliverable again if the underlying issue was resolved (e.g., the user recreated their account). You can specify a custom retention period when adding suppressions manually:

Python
cURL

# Suppress for 90 days
client.suppressions.create(
    email="[email protected]",
    reason="hard_bounce",
    days=90
)

# Suppress for 365 days
client.suppressions.create(
    email="[email protected]",
    reason="complaint",
    days=365
)

curl -X POST https://api.arkhq.io/v1/suppressions \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "reason": "hard_bounce",
    "days": 90
  }'

Best Practices

Check suppressions before sending

Especially for older email lists, check each address before sending. This prevents wasted API calls and maintains clean metrics.

Never remove hard bounced emails

Hard bounces are permanent failures. Removing them from the suppression list will just cause another bounce, harming your reputation. Only remove if you’ve verified the address is now valid.

Act on complaints immediately

If someone marks your email as spam, they don’t want to hear from you. Keep them suppressed and update your application’s user preferences.

Sync with your database

Use webhooks to keep your user database updated. Mark email addresses as invalid when they bounce so you don’t need to query suppressions on every send.

Clean your list proactively

Don’t wait for bounces. Periodically remove subscribers who haven’t engaged in 6+ months, and use double opt-in to verify new addresses.

Monitor your bounce rate

Keep your bounce rate below 2%. Higher rates indicate list quality issues and will harm deliverability.

API Reference

View suppression API documentation

Getting Started

Guides

Concepts

Reference

Why Suppressions Matter

Automatic Suppressions

Viewing Suppressions

List All Suppressions

Filter by Reason

Check Specific Email

Manual Suppression

Bulk Add Suppressions

Removing Suppressions

Sync with Your Database

Understanding Bounce Types

Hard Bounces (Permanent Failures)

Soft Bounces (Temporary Failures)

Bounce vs Hard Fail

Suppression Expiration

Best Practices

API Reference

Getting Started

Guides

Concepts

Reference

​Why Suppressions Matter

​Automatic Suppressions

​Viewing Suppressions

​List All Suppressions

​Filter by Reason

​Check Specific Email

​Manual Suppression

​Bulk Add Suppressions

​Removing Suppressions

​Sync with Your Database

​Understanding Bounce Types

​Hard Bounces (Permanent Failures)

​Soft Bounces (Temporary Failures)

​Bounce vs Hard Fail

​Suppression Expiration

​Best Practices

API Reference

Why Suppressions Matter

Automatic Suppressions

Viewing Suppressions

List All Suppressions

Filter by Reason

Check Specific Email

Manual Suppression

Bulk Add Suppressions

Removing Suppressions

Sync with Your Database

Understanding Bounce Types

Hard Bounces (Permanent Failures)

Soft Bounces (Temporary Failures)

Bounce vs Hard Fail

Suppression Expiration

Best Practices