Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt

Use this file to discover all available pages before exploring further.

Zavu monitors your email deliverability to protect your sender reputation and ensure high delivery rates. This guide explains how the system works and what happens when bounce rates exceed safe thresholds.

​
Why Email Health Matters

Email providers like Gmail, Yahoo, and corporate mail servers track sender reputation. A high bounce rate indicates poor list hygiene and can result in:
  • Your emails being marked as spam
  • Reduced inbox placement
  • Complete blocking by email providers
  • Amazon SES account suspension
Zavu automatically monitors and enforces bounce rate limits to protect both your reputation and our shared sending infrastructure.

​
Bounce Rate Thresholds

We track your bounce rate over a rolling 7-day window:
Bounce RateStatusImpact
< 5%HealthyNo restrictions
5% - 8%WarningYou’ll receive a notification to review your email list
8% - 10%Email PausedEmail sending is paused; SMS and WhatsApp continue working
> 10%SuspendedAll API access is suspended until resolved
Amazon SES has a strict 0.1% complaint rate threshold. If recipients mark your emails as spam, your account may be suspended immediately.

​
Types of Bounces

​
Hard Bounces

Permanent delivery failures that immediately add the email to the suppression list:
  • Invalid address: Email address doesn’t exist
  • Domain not found: Domain has no mail servers
  • Rejected: Server permanently rejected the message

​
Soft Bounces

Temporary delivery failures that are tracked:
  • Mailbox full: Recipient’s mailbox is full
  • Server temporarily unavailable: Try again later
  • Message too large: Email exceeded size limits
After 3 soft bounces to the same address within 7 days, the email is automatically added to the suppression list for 7 days.

​
Email Suppression List

The suppression list prevents sending to addresses that have bounced or complained. This protects your bounce rate from known-bad addresses. When you try to send to a suppressed email: 
{
  "code": "bad_request",
  "message": "Cannot send to user@example.com: Email is suppressed (hard_bounce)"
}

​
Suppression Reasons

ReasonDurationDescription
hard_bouncePermanentEmail address is invalid
soft_bounce7 daysTemporary issue, will retry after expiration
complaintPermanentRecipient marked email as spam
unsubscribePermanentRecipient unsubscribed
manualPermanentManually added by you

​
What Happens When You’re Suspended

​
Warning Level (5-8%)

  • Email notification sent to account owner
  • Yellow banner appears in dashboard
  • No sending restrictions yet
  • Action required: Review and clean your email list

​
Email Paused Level (8-10%)

  • Email sending is blocked
  • SMS and WhatsApp continue working
  • Orange banner appears in dashboard
  • Action required: Remove invalid emails and contact support

​
Suspended Level (>10%)

  • All API access is blocked (400 errors)
  • Red banner appears in dashboard
  • Action required: Contact support immediately

​
Checking Your Email Health

​
Dashboard

Visit the Email Health page in your dashboard to see:
  • Current bounce rate and status
  • Suppressed email addresses
  • Suspension history

​
API

Check if an email is suppressed before sending: 
// The API automatically checks suppression
// You'll get an error if the email is suppressed
try {
  await zavu.messages.send({
    to: "user@example.com",
    channel: "email",
    subject: "Hello",
    text: "Your message"
  });
} catch (error) {
  if (error.code === "bad_request" && error.message.includes("suppressed")) {
    console.log("Email is suppressed, skipping");
  }
}

​
How to Maintain Good Email Health

​
1. Verify Email Addresses

Use double opt-in to ensure email addresses are valid: 
// Step 1: User signs up
await zavu.messages.send({
  to: userEmail,
  channel: "email",
  subject: "Verify your email",
  text: `Click here to verify: ${verificationLink}`
});

// Step 2: Only add to your list after they click

​
2. Clean Your List Regularly

Remove emails that:
  • Haven’t opened emails in 6+ months
  • Have bounced previously
  • Have unsubscribed

​
3. Use Engagement-Based Sending

Send more frequently to engaged users, less to inactive ones.

​
4. Monitor Bounce Rates

Check your Email Health dashboard weekly. Address issues before reaching thresholds.

​
5. Handle Bounces Gracefully

// When a bounce webhook arrives, update your database
app.post("/webhooks/zavu", (req, res) => {
  const { type, data } = req.body;

  if (type === "message.failed" && data.errorCode === "bounce") {
    // Mark user as having invalid email
    await db.users.update({
      where: { email: data.to },
      data: { emailInvalid: true }
    });
  }
});

​
Resolving a Suspension

If your account is suspended:
  1. Review the Email Health dashboard to understand the cause
  2. Export and clean your email list - remove all bounced addresses
  3. Contact support at support@zavu.dev with:
    • Your project ID
    • Steps you’ve taken to clean your list
    • Your plan to prevent future issues
Suspensions are typically resolved within 24-48 hours after you’ve demonstrated list cleanup.

​
Best Practices Summary

Do

  • Use double opt-in
  • Clean lists regularly
  • Monitor bounce rates weekly
  • Handle bounces in webhooks
  • Remove unsubscribes immediately

Don't

  • Buy or rent email lists
  • Send to old, unverified lists
  • Ignore bounce notifications
  • Re-add bounced emails
  • Send without permission