# Deliverability and warmup (/advanced/deliverability) Related: [Webhooks](/advanced/webhooks.md), [WebSockets](/advanced/websockets.md), [Agent safety](/advanced/safety.md), [Custom domains](/advanced/custom-domains.md), [Build a multi-tenant platform](/advanced/multi-tenant.md), [AgentID public-key authentication](/advanced/agentid.md) # Keep agent mail out of spam AgentMail authenticates your sending domain, suppresses addresses that bounce or complain, screens outbound content, and monitors bounce and complaint rates automatically. Use the warmup ramp and the metrics endpoint when sending from a new domain or scaling cold outreach. ## Do this Compute the bounce rate over a window and gate each ramp increase on it. Every parameter of the metrics endpoint is optional: ```bash curl "https://api.agentmail.to/v0/metrics/events?event_types=message.sent&event_types=message.bounced&period=86400" \ -H "Authorization: Bearer $AGENTMAIL_API_KEY" ``` The response holds event counts per time bucket for each requested event type. Divide total `message.bounced` count by total `message.sent` count. Hold volume at the current warmup stage until the bounce rate is under 2 percent and the complaint rate is under 0.1 percent, then make the next increase. ## SDK Install: `npm install agentmail` (TypeScript), `pip install agentmail` (Python). * Query event counts: `client.metrics.queryEvents({ eventTypes, start, period })` (TypeScript), `client.metrics.query_events(event_types=..., start=..., period=...)` (Python). Full reference: [/integrations/sdks-and-cli](/integrations/sdks-and-cli). ## Facts * AgentMail sets up SPF, DKIM, and DMARC. Shared `@agentmail.to` addresses already pass with nothing to configure. A custom domain publishes the records AgentMail generates at registration. * A domain can hold only one SPF record. Merge AgentMail's mechanism into an existing SPF record instead of adding a second one. * AgentMail holds the private DKIM signing key for a custom domain. Receivers verify signatures against the public key published in DNS. * AgentMail's DMARC record uses `p=reject`, the strictest policy. * An address that hard bounces, files a spam complaint, or unsubscribes is suppressed automatically. Sends to it fail with `403` `message_rejected`. The suppression entry is read-only and only support can remove it. * Outbound content is scored for spam patterns. A message classified as spam can be rejected with `403` `message_rejected` that names the reason. * Warning email threshold: a 10 percent bounce rate or a 0.5 percent complaint rate in the last 1,000 sends in the trailing 24 hours. * Suspension threshold: a 20 percent bounce rate or a 1 percent complaint rate. Appeal by writing [support@agentmail.cc](mailto:support@agentmail.cc). * Warmup ramp for a new domain: days 1 to 3 send 10 to 20 daily to the most engaged recipients, days 4 to 7 send 50 to 100 to known verified addresses, days 8 to 14 send 200 to 500 while watching bounce rates, days 15 to 21 send 500 to 1,000 while watching complaints, days 22 to 30 send 1,000 to 5,000, day 30 onward full volume. * Each warmup stage is a checkpoint. Hold volume until the stage's bounce and complaint numbers come back healthy before increasing. Send only to validated addresses during warmup. * Healthy bounce rate: under 2 percent. Outside it, pause and clean the recipient list. * Healthy spam complaint rate: under 0.1 percent. Outside it, reduce volume and review the content. * A bounce rate past 5 percent or a spam complaint spike at any stage means slow down immediately. * AgentMail flags an account for review when, across at least 50 recent sends, the bounce rate exceeds 10 percent, or when nearly every message goes to a different address, which reads as a cold blast. * Free plan recipient ramp: an organization can email at most 5 distinct recipients in its first 24 hours and 10 distinct recipients, cumulative, in its first week. Senders who emailed the organization first are exempt. * `GET /v0/metrics/events` returns event counts per time bucket. An event type with no events in the window comes back as an empty array. * The same counters are charted on the Metrics page in the AgentMail Console at console.agentmail.to. Google Postmaster Tools at postmaster.google.com shows Gmail's own reputation and spam-rate measurements for a domain. * Replies to inbound mail build reputation faster than cold sends because they demonstrate two-way engagement. * Ten emails each from 10 inboxes on a domain warm it faster than 100 emails from one inbox. Split high volume across separately registered subdomains, each warmed on its own, so a damaged reputation can be cycled out. * First-touch content guidance: short plain text, one reason to reply, personalized. Avoid trigger words like "free", "buy now", and "urgent", all-caps subjects, and stacked exclamation marks. Keep images and open tracking out (open tracking embeds a tiny image). Hold links until the recipient replies and never use URL shorteners. * Warmup services such as Instantly and Smartlead connect over IMAP and SMTP with the standard server settings. Keep warmup and live outreach in separate inboxes. Transactional mail and replies to inbound messages do not need a warmup service. ## Not supported * There is no API call to remove an automatic suppression entry. The entry is read-only and only support can remove it. * Do not reintroduce a suppressed address through another list. * The shared `@agentmail.to` domain is not a foundation for production sending. Its reputation is shared across every AgentMail user. * Never use a new domain to absorb a sudden full-volume campaign, and never send to purchased or scraped lists during warmup. ## Errors | Error | HTTP | Cause | Fix | | ------------------ | ---- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `message_rejected` | 403 | The recipient is suppressed after a hard bounce, spam complaint, or unsubscribe. | The entry is read-only. Correct the cause, and email [support@agentmail.cc](mailto:support@agentmail.cc) if the entry genuinely needs review. | | `message_rejected` | 403 | Outbound content was classified as spam. The message names the reason. | Revise the content and resend. | ## Verify ```bash curl "https://api.agentmail.to/v0/metrics/events?event_types=message.sent&event_types=message.bounced&period=86400" \ -H "Authorization: Bearer $AGENTMAIL_API_KEY" ``` Success returns per-bucket counts for each requested event type, with an empty array for a type that has no events in the window, so rate math works from day one. ## Related * [/extras/deliverability-fundamentals](/extras/deliverability-fundamentals) - how authentication, reputation, and recipient feedback interact behind these practices. * [/advanced/multi-tenant](/advanced/multi-tenant) - give every customer their own pod, domain, and scoped key. * [/advanced/custom-domains](/advanced/custom-domains) - register your own domain, customize DMARC policy, scale across multiple domains. * [/advanced/plans-and-usage](/advanced/plans-and-usage) - full entitlement list including the Free plan recipient ramp. * [/core/imap-smtp](/core/imap-smtp) - server settings for connecting warmup services.