You give your AI agent a real mailbox, it sends its first batch of email, and half of it lands in spam. The agent did nothing wrong. The domain did — it's new, it has no sending history, and mailbox providers treat an unknown domain that suddenly sends volume the same way they treat a spammer. Deliverability is the work of proving the mail is really yours, sending at a pace providers trust, and watching the signals that say whether recipients want it.

An Agent Account sends from a domain you own, so its inbox placement is yours to manage like any other mail from your company. This post is a practical playbook for getting and keeping an agent in the inbox, from two angles: the HTTP API for your backend, and the Nylas CLI for the terminal. I work on the CLI, so the terminal commands below are the ones I reach for when I'm wiring up monitoring.

The deliverability checklist

Five things decide whether an Agent Account reaches the inbox, and you can act on all of them before sending at volume. Work them in order — authentication first, because nothing else matters if recipient servers can't confirm the mail is yours, then pace and monitoring once mail is flowing.

1. Authenticate the domain with DKIM and SPF as part of domain verification.
2. Set up DMARC so providers know how to treat mail that fails authentication.
3. Warm up a new domain before sending at volume, over roughly four weeks.
4. Monitor bounces and complaints through the deliverability webhooks.
5. Stay under the bounce and complaint thresholds that pause sending.

The rest of this post covers each one with the commands and request bodies to wire it up.

Authenticate with DKIM and SPF

Authentication is the foundation, and for an Agent Account it rides on two records you already publish during domain setup. DKIM adds a cryptographic signature proving the message wasn't altered and really came from your domain; SPF authorizes the sending infrastructure to send on your behalf. Both are verified before a custom domain can host accounts, so a verified Agent Account domain is already DKIM- and SPF-authenticated.

You can drive domain registration and verification from the CLI. nylas domains create registers the domain, nylas domains dns shows the records to publish, and nylas domains verify triggers verification once they propagate:

nylas domains create agents.yourcompany.com
nylas domains dns agents.yourcompany.com
nylas domains verify agents.yourcompany.com

The same flow runs over the Manage Domains API, which returns each record's host, type, and value to copy into your DNS provider. Verification usually succeeds within a few minutes, though DNS can take up to 24 hours depending on the record's TTL — the DNS setup guide walks through publishing the records at each provider. Once the domain is verified, DKIM and SPF are done — the one authentication layer left is DMARC, which you add yourself.

Set up DMARC in stages

DMARC tells receiving servers what to do when a message claiming to be from your domain fails authentication, and it reports who's sending as you. It builds on DKIM and SPF: a message passes DMARC when either one passes and aligns with the domain in the visible From address. Because an Agent Account signs with your domain's DKIM key and sends from your verified domain, alignment works as soon as you publish a DMARC record.

Roll it out in three stages so you never block legitimate mail before confirming everything authenticates. Add one TXT record at _dmarc.yourdomain.com, then tighten the policy over a few weeks as the reports come back clean:

v=DMARC1; p=none; rua=mailto:dmarc-reports@yourdomain.com; pct=100

1. Monitor with p=none. Mail is delivered normally, but providers send aggregate reports to your rua address so you can confirm your agent's mail authenticates and aligns.
2. Quarantine with p=quarantine. Once reports look clean, send failing mail to spam. Ease in with pct=25 to apply the policy to a quarter of failing mail, then raise it to 100.
3. Reject with p=reject. The end state, where receiving servers refuse mail that fails DMARC outright.

Give each stage a couple of weeks of clean reports before tightening. DMARC isn't part of domain verification — it's a separate record you manage in DNS, not through the API — but it's the most effective protection you can add against spoofing. Point the rua address at a mailbox or a monitoring service you actually check.

Warm up a new domain

A brand-new domain has no reputation, so a sudden burst of mail looks like spam and gets filtered. Warming up means raising volume gradually, over roughly four weeks, while real recipients open and reply. The reputation an Agent Account builds is tied to its domain, so warming matters most when you launch a new custom domain or split traffic across several — warm each one on its own schedule, since reputation doesn't transfer between domains.

This is a representative ramp toward a daily target of 500 to 1,000 messages, increasing 10 to 20 percent each day within a week:

Two things matter as much as the numbers. Spread sends across business hours rather than firing them all at once, with a delay between messages to mimic natural patterns. And send only to recipients who expect the mail and will engage, because opens, clicks, and especially replies are the strongest positive signals you can generate. A send during warm-up is a normal Agent Account send — the same POST /v3/grants/{grant_id}/messages/send you'd use any time, or nylas email send from the terminal:

nylas email send \
  --to engaged-recipient@example.com \
  --subject "Your booking confirmation" \
  --body "Thanks for booking with us. Here are your details..."

Monitor delivery with webhooks

You can't manage deliverability you can't see, and for an Agent Account the four deliverability webhooks are your real-time signal. Subscribe to message.delivered, message.bounced, message.complaint, and message.rejected to track exactly what happens to each outbound message — the same events Nylas uses to calculate your bounce and complaint rates. From the CLI, one command registers them:

nylas webhook create \
  --url https://yourapp.example.com/webhooks/nylas \
  --triggers message.delivered,message.bounced,message.complaint,message.rejected

The same subscription over the API is a POST /v3/webhooks with the triggers and a callback URL — see the Agent Account webhook notifications reference for each event's payload schema:

curl --request POST \
  --url "https://api.us.nylas.com/v3/webhooks" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "trigger_types": [
      "message.delivered",
      "message.bounced",
      "message.complaint",
      "message.rejected"
    ],
    "callback_url": "https://yourapp.example.com/webhooks/nylas"
  }'

Wire these into your own logic. message.delivered confirms a message reached the recipient's server, message.bounced is a hard bounce, message.complaint means the recipient marked it as spam, and message.rejected fires when an attachment contained a virus, per the webhook notifications reference. Pause or slow your outbound when bounces or complaints climb, and stop mailing any address that hard-bounces. Catching a problem in your own telemetry is what keeps you under the thresholds that pause sending.

Stay under the bounce and complaint thresholds

Nylas tracks a rolling bounce rate and complaint rate for each Agent Account, and crossing either threshold has consequences. Bounce rate is hard bounces — addresses that don't exist, not transient soft bounces — divided by your recent send volume. Complaint rate is spam reports divided by recent volume, counted only against recipient domains that report complaints back to senders. The denominator is a recent volume window, so the rate stays meaningful whether you send a hundred messages a day or a million.

Here's where each rate puts an account:

The complaint threshold is low enough — 0.1% — that even a handful of recipients reporting your mail can put a low-volume account under review. Under review is silent to your application; a pause returns immediate feedback on the send call.

What a pause looks like to your code

When enforcement kicks in, your send requests start failing, and the status code tells you which problem you have. These are the three you'll see, and they call for different handling:

One thing to design for: a reputation pause does not clear itself on a timer. Resuming requires Nylas to lift it, so you contact support with the bounce or complaint source and the fix you've applied. That's the opposite of a 429, which clears as soon as you slow down. An abuse restriction returns 403 with the body send blocked by abuse restriction and is also cleared by support, not by waiting.

Sending limits that interact with deliverability

Beyond reputation, a few hard limits shape how an agent can send, and hitting them returns 429. Each Agent Account has a daily send quota — 200 messages on the free plan, with no daily cap on paid plans by default. Your organization shares a per-second rate too: all sandbox applications pool to 1 request per second, and all production applications to 5 per second. A single message should address at most 50 recipients across to, cc, and bcc, and must be 25 MB or less in total size.

These interact with warm-up in a way that's easy to miss. Calendar invitations count against the daily send quota, and when an account is over quota the event still saves but the invitation is skipped silently — so an agent that both emails and schedules can quietly stop notifying people. Batch large audiences into groups of 50 or fewer, and keep your per-second send rate under the pooled cap so a burst doesn't start returning 429 mid-warm-up.

Keep in mind

A short list of habits keeps an agent inside the deliverability envelope once it's sending for real. Each one heads off a specific way reputation slips.

• Validate addresses before sending and skip any that have hard-bounced before. Hard bounces are the fastest way to a paused account.
• Honor unsubscribe and removal requests immediately. At a 0.1% complaint threshold, ignoring a few costs you.
• Wire up all four deliverability triggers and pause your own outbound when bounced, complaint, or rejected rates climb — you'll see it in your telemetry before Nylas tells you.
• Keep the From domain consistent with the domain your accounts are verified on, so DMARC alignment holds. Forwarding breaks SPF, but DKIM survives it, which is exactly why DMARC accepts a pass from either.
• Warm each domain separately. Reputation doesn't transfer, so a second domain starts from zero no matter how good the first one's record is.

Wrapping up

Deliverability for an agent is the same discipline as for any sender, with the advantage that you own the domain end to end. Authenticate first, layer DMARC on in stages, warm the domain over four weeks, and let the four deliverability webhooks feed your own pause-and-slow logic. The thresholds are strict — 10% bounces or 0.5% complaints pauses an account — but every signal that feeds them is one you can watch in real time and act on before Nylas has to.

Where to go next:

• Email deliverability for Agent Accounts — DMARC setup, alignment, and reading reports
• Domain warm-up guide — the full ramp schedule and a daily send script
• Agent Account usage limits — quotas, thresholds, and what pauses sending
• Agent Account webhook notifications — schemas for the delivery, bounce, complaint, and rejection events