Most "give every tenant its own AI agent" walkthroughs end at the moment the grant exists. You register a domain, create the agent account, fire off a "welcome, I'm your assistant" email, and call the onboarding done. That's fine right up until the first batch of those emails lands in spam — because a brand-new tenant domain has zero sending reputation, and a cold blast of mail from an unknown domain is exactly the shape mailbox providers are trained to filter.
I work on the Nylas CLI, so the terminal commands below are the exact ones I reach for when I'm scripting tenant provisioning. The interesting part of this post isn't deliverability in the abstract — there's already , which signs each request with four custom headers. So the curl below is real, but you'll be computing a signature, not pasting an API key:
# Register the tenant's domain (Manage Domains API — Service Account auth)
curl -X POST "https://api.us.nylas.com/v3/admin/domains" \
-H "Content-Type: application/json" \
-H "X-Nylas-Signature: <BASE64_SIGNATURE>" \
-H "X-Nylas-Kid: <SERVICE_ACCOUNT_ID>" \
-H "X-Nylas-Nonce: <NONCE>" \
-H "X-Nylas-Timestamp: 1742932766" \
-d '{
"name": "Acme tenant 4821 mail",
"domain_address": "mail.tenant4821.example.com"
}'
Then you fetch the DNS records to publish and trigger verification:
# Get the records to publish for a verification type (ownership, dkim, spf, feedback, mx)
curl -X POST "https://api.us.nylas.com/v3/admin/domains/<DOMAIN_ID>/info" \
-H "Content-Type: application/json" \
-H "X-Nylas-Signature: <BASE64_SIGNATURE>" \
-H "X-Nylas-Kid: <SERVICE_ACCOUNT_ID>" \
-H "X-Nylas-Nonce: <NONCE>" \
-H "X-Nylas-Timestamp: 1742932766" \
-d '{ "type": "dkim" }'
# After you add the records at your DNS provider, trigger the check for that type
curl -X POST "https://api.us.nylas.com/v3/admin/domains/<DOMAIN_ID>/verify" \
-H "Content-Type: application/json" \
-H "X-Nylas-Signature: <BASE64_SIGNATURE>" \
-H "X-Nylas-Kid: <SERVICE_ACCOUNT_ID>" \
-H "X-Nylas-Nonce: <NONCE>" \
-H "X-Nylas-Timestamp: 1742932766" \
-d '{ "type": "dkim" }'
Both /info and /verify take a required type in the body — one of ownership, mx, spf, dkim, or feedback — so you run the pair once per record type. For Agent Accounts you verify all five (ownership, dkim, spf, feedback, and mx); that mx record is the extra one Agent Accounts need beyond what Transactional Send requires. There is no CLI for this flow — domain registration and verification are Dashboard-or-API only, so the curl above (Service Account auth) is the programmatic path; I'm not inventing a nylas domain command because none exists. Configure the DNS records before the first /verify call to dodge DNS-caching delays. If verification fails with correct records, give it up to 24 hours (usually it's minutes, depending on TTL).
If you'd rather skip DNS entirely while you build the pipeline, you can provision the agent on a free *.nylas.email trial subdomain — but a real per-tenant domain is the point of this exercise, so I'll assume a custom one.
Step 2: Provision the tenant's Agent Account
With the domain verified, the grant is one call. Create it with POST /v3/connect/custom, provider: "nylas", and settings.email on the verified domain. No refresh token, no OAuth round-trip:
# Provision the tenant's agent — API
curl -X POST "https://api.us.nylas.com/v3/connect/custom" \
-H "Authorization: Bearer <NYLAS_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"provider": "nylas",
"name": "Acme Support Agent",
"settings": {
"email": "[email protected]"
}
}'
The optional top-level name sets the agent's display name. The response carries the grant_id — that's your handle for everything downstream.
The CLI collapses this to one command. It always uses provider=nylas, auto-creates the Nylas connector the first time if it doesn't exist, and the API auto-creates a default workspace and policy for the account:
# Provision the tenant's agent — CLI
nylas agent account create [email protected] \
--name "Acme Support Agent"
I verified both --name (display name, 1–256 chars) and --app-password (an optional IMAP/SMTP app password) on nylas agent account create. There is deliberately no --workspace flag on create — the workspace and its policy come into existence automatically, and you attach a custom policy afterward. Which is exactly what step 3 is for.
Step 3: Cap the daily ramp with a policy
Here's the division of labor that matters: your application decides the warm-up schedule and which recipients to send to. Nylas enforces the ceiling. The ramp logic — how many to send today, spread across the day, to whom — lives in your code. But you can make Nylas backstop your ramp with a hard daily send cap, so a bug in your scheduler can't accidentally blast 1,000 emails on day one.
That cap is a policy field: limit_count_daily_email_sent. Create a policy with this week's number, then attach it to the agent's workspace.
# Create a policy that caps daily sends to week 1's number — API
curl -X POST "https://api.us.nylas.com/v3/policies" \
-H "Authorization: Bearer <NYLAS_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "Warm-up week 1 — tenant 4821",
"limits": {
"limit_count_daily_email_sent": 15
}
}'
The CLI mirrors it. nylas agent policy create takes --name for a simple policy, or --data / --data-file for a full request body — and the limits live under a limits object, so you pass the JSON through --data:
# Create the capped policy — CLI
nylas agent policy create \
--data '{"name":"Warm-up week 1 — tenant 4821","limits":{"limit_count_daily_email_sent":15}}'
Then attach the policy to the workspace the account was created in. Grab the workspace ID from nylas workspace list. On the API side this is a PATCH /v3/workspaces/{workspace_id} with the policy_id in the body:
# Attach the policy to the agent's workspace — API
curl --request PATCH \
--url "https://api.us.nylas.com/v3/workspaces/<WORKSPACE_ID>" \
--header "Authorization: Bearer <NYLAS_API_KEY>" \
--header "Content-Type: application/json" \
--data '{
"policy_id": "<POLICY_ID>"
}'
The CLI is the same operation in one line:
# Attach the policy to the agent's workspace — CLI
nylas workspace update <WORKSPACE_ID> --policy-id <POLICY_ID>
I checked nylas workspace update: --policy-id attaches a policy, and passing --policy-id "" detaches it — which maps to setting policy_id to null in the API body (plan maximums apply when nothing's attached). At the end of each warm-up week you bump the policy's limit_count_daily_email_sent to the next tier and the ceiling rises with your ramp. The cap is a safety net, not the schedule — your app still has to pace the actual sends.
Raise the cap each week
When week 2 starts and your ramp climbs, update the same policy in place rather than creating a new one. The update is a PUT /v3/policies/{policy_id} — all fields are optional, so you send only the limit you're changing, nested under limits:
# Raise the daily send cap for week 2 — API
curl -X PUT "https://api.us.nylas.com/v3/policies/<POLICY_ID>" \
-H "Authorization: Bearer <NYLAS_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"limits": {
"limit_count_daily_email_sent": 75
}
}'
nylas agent policy update takes the policy ID and the same partial JSON body through --data:
# Raise the daily send cap for week 2 — CLI
nylas agent policy update <POLICY_ID> \
--data '{"limits":{"limit_count_daily_email_sent":75}}'
Repeat at the start of week 3 (300) and week 4 (1000). Because the update is partial, you never have to re-send the rest of the policy — just the new ceiling.
Step 4: The warm-up ramp itself
This is the schedule, straight from the you can run daily from cron that handles the pacing for one day's target; adapt it to send through your agent's grant instead of the Transactional Send endpoint, and update the daily target each week to match the table above.
Step 5: Watch bounces and complaints so you can back off
You can't manage deliverability you can't see. While the ramp runs, the thing that tells you whether reputation is holding is the stream of deliverability webhooks Agent Accounts emit: message.delivered, message.bounced, message.complaint, and message.rejected. These are the same events Nylas uses to calculate your bounce and complaint rates — the rates that, if they climb too high, pause sending. Catching a dip in your own telemetry is what keeps you under those thresholds.
Webhooks are application-scoped, not grant-scoped — and that's a feature when you're running many tenants. You subscribe once at the app level, and events for every tenant's agent arrive at the same endpoint, each payload carrying a grant_id you filter on. So you don't re-subscribe per tenant; provision the subscription once and route by grant_id. Subscribe with POST /v3/webhooks:
# Subscribe to deliverability webhooks — API (app-scoped, once)
curl -X POST "https://api.us.nylas.com/v3/webhooks" \
-H "Authorization: Bearer <NYLAS_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"trigger_types": [
"message.delivered",
"message.bounced",
"message.complaint",
"message.rejected"
],
"webhook_url": "https://hooks.yourcompany.com/nylas/deliverability"
}'
The CLI creates the same subscription with --url and --triggers (comma-separated, or repeated flags):
# Subscribe to deliverability webhooks — CLI
nylas webhook create \
--url https://hooks.yourcompany.com/nylas/deliverability \
--triggers message.delivered,message.bounced,message.complaint,message.rejected
Run nylas webhook triggers to list every available trigger type if you want to confirm the names yourself. Honest CLI note: the signal you act on — the bounce and complaint events themselves — arrives over the webhook stream and gets handled by your receiver, which is application code, not a CLI command. The CLI helps you set the subscription up and verify deliveries (nylas webhook verify checks a signature locally; nylas webhook server runs a local receiver for testing), but reacting to a complaint spike by lowering the ramp is logic you write.
Wire those events into your back-off rule: when bounces or complaints climb for a tenant's grant_id, slow or pause that tenant's ramp, and stop mailing any address that hard-bounces or complains. One quick implementation note since these matter in production — the API delivers at-least-once (up to three attempts per event), so dedupe on the top-level notification id, which stays constant across retries of the same event. The inner message id identifies the message; the notification id identifies the delivery.
Guardrails: DMARC and per-tenant isolation
Two things to get right before you scale this across tenants.
Publish DMARC, but roll it out in stages. DKIM and SPF are already verified, but DMARC is the layer you add. Publish a record at _dmarc.<your-sending-subdomain> starting at p=none so mail is delivered normally while providers send you aggregate reports — you confirm your agent's mail authenticates and aligns before you tighten anything. Once reports are clean, move to p=quarantine (you can ease in with pct=25), then finally p=reject. Give each stage a couple of weeks of clean reports. Because Agent Accounts sign with your domain's DKIM key and send from your verified domain, alignment works out of the box with relaxed alignment, which is the default they're set up for.
Reputation doesn't transfer between domains. If your model is one domain per tenant, you warm each domain on its own schedule. The reputation a freshly provisioned agent builds is tied to its domain — there's no shared head start across tenants. That's the cost of per-tenant domain isolation, and it's why the warm-up belongs in your provisioning pipeline rather than as a one-time thing you did for the first tenant and forgot about. Every new tenant on a new domain starts the four-week clock over.
What's next
— DMARC staging, webhook monitoring, and SPF/DKIM alignment troubleshooting
— provisioning, policies, and the grant model
- Industry playbooks hub: https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md
SOCIAL SHARE CARD GENERATOR