Troubleshooting

Why are my emails bouncing?

Diagnose and resolve email bounce issues.

A bounced email means the recipient’s mail server rejected your message. Understanding the bounce type helps you take the right action.

Bounce types

Permanent bounces

The address is permanently unreachable. Common causes:

  • The email address does not exist
  • The domain does not exist
  • The recipient’s mailbox has been deleted

Action: Remove permanently bounced addresses from your sending lists immediately. Continuing to send to them will damage your sender reputation.

Transient bounces

Temporary delivery failure. Common causes:

  • Recipient’s mailbox is full
  • Recipient’s mail server is temporarily unavailable
  • Message is too large
  • Greylisting (server temporarily rejects first-time senders)

Action: AgentMail automatically retries transient bounces. If delivery fails after multiple attempts, the bounce is treated as permanent.

Monitoring bounces with webhooks

Subscribe to the message.bounced webhook event to track bounces in real time:

TypeScript
1import { serialization } from "agentmail";
2
3async function handleWebhook(payload: Record<string, unknown>) {
4  if (payload.event_type === "message.bounced") {
5    const event = await serialization.events.MessageBouncedEvent.parse(payload);
6
7    console.log(`Bounce type: ${event.bounce.type}`);       // "Permanent" or "Transient"
8    console.log(`Sub type: ${event.bounce.subType}`);        // e.g., "General"
9    console.log(`Message: ${event.bounce.messageId}`);
10
11    for (const recipient of event.bounce.recipients) {
12      console.log(`Bounced address: ${recipient.address}`);
13
14      if (event.bounce.type === "Permanent") {
15        // Remove from your sending lists
16        await removeFromList(recipient.address);
17      }
18    }
19  }
20}

Register a webhook to receive bounce events:

TypeScript
1import { AgentMailClient } from "agentmail";
2
3const client = new AgentMailClient({ apiKey: "am_..." });
4
5await client.webhooks.create({
6  url: "https://your-domain.ngrok-free.app/webhooks",
7  events: ["message.bounced"],
8});

Automatic suppression

AgentMail automatically prevents you from sending to addresses that have previously bounced, been rejected, or filed a spam complaint. This protects your sender reputation. Keep your account bounce rate under 4%, otherwise your account may be placed under review.

Keeping bounce rates low

PracticeWhy it matters
Validate addresses before sendingCatches typos and nonexistent addresses before they bounce
Remove permanent bounces immediatelyRepeated sends to invalid addresses damage reputation fast
Avoid purchased or scraped listsThese lists have high rates of invalid addresses
Warm up new domains graduallySudden high volume from a new domain triggers suspicion
Monitor bounce rateKeep it under 2% for healthy reputation; under 4% to avoid account review

For more on maintaining healthy sending metrics, see the Email Deliverability best practices.