DEV Community

Qasim Muhammad
Qasim Muhammad

Posted on

Agent Accounts Quickstart in Python

#python #email #api #tutorial

A connected Gmail grant starts with an OAuth consent screen and ends with a refresh token you have to babysit; a Nylas Agent Account starts and ends with one POST request. Same API surface afterward — same messages endpoints, same webhooks, same calendar — but the provisioning story couldn't be more different, and that difference is what makes these hosted mailboxes such a natural fit for Python automation, agents, and test harnesses.

Agent Accounts are in beta, and the official quickstart gets you from nothing to a sending-and-receiving mailbox in under 5 minutes using curl. Here's the whole flow as a Python script.

Step 0: prerequisites

You need an API key (run nylas init with the CLI, or use the Dashboard) and a domain. The fast path for testing: register a *.nylas.email trial subdomain from the Dashboard — no DNS records, instantly usable. Custom domains need MX and TXT records published at your DNS provider, with automatic verification once they propagate; save that for production.

import os
import requests

BASE = "https://api.us.nylas.com"
HEADERS = {
    "Authorization": f"Bearer {os.environ['NYLAS_API_KEY']}",
    "Content-Type": "application/json",
}
Enter fullscreen mode Exit fullscreen mode

Step 1: provision the account

POST /v3/connect/custom with "provider": "nylas". No refresh token — just an email address on a registered domain:

resp = requests.post(
    f"{BASE}/v3/connect/custom",
    headers=HEADERS,
    json={
        "provider": "nylas",
        "settings": {"email": "test@your-application.nylas.email"},
    },
)
resp.raise_for_status()
grant_id = resp.json()["data"]["id"]
print(f"Agent Account live: {grant_id}")
Enter fullscreen mode Exit fullscreen mode

Save that grant_id — per the docs, you'll use it in every subsequent call. The mailbox works with every existing endpoint from this moment on.

If you want policies or mail rules applied, add a top-level workspace_id to the same request body; the account inherits the workspace's limits, spam settings, and rules. Omit it and the account lands in your application's default workspace.

Worth knowing there are two other creation paths to the same grant: nylas agent account create test@your-application.nylas.email from the CLI (it prints the grant ID, and nylas agent account list shows the fleet), or Agent Accounts → Accounts → Create account in the Dashboard. The POST above is the path you'll automate, which is why this script uses it.

Step 2: receive mail

Polling first, because it needs no infrastructure. List the inbox with the standard messages endpoint:

inbox = requests.get(
    f"{BASE}/v3/grants/{grant_id}/messages",
    headers=HEADERS,
    params={"limit": 5},
).json()

for msg in inbox["data"]:
    print(msg["subject"], "-", msg["snippet"])
Enter fullscreen mode Exit fullscreen mode

Fetching one message with its full body is the same route plus the message ID: GET /v3/grants/{grant_id}/messages/{message_id}.

For push instead of poll, register a message.created webhook:

requests.post(
    f"{BASE}/v3/webhooks",
    headers=HEADERS,
    json={
        "trigger_types": ["message.created"],
        "callback_url": "https://yourapp.example.com/webhooks/nylas",
    },
)
Enter fullscreen mode Exit fullscreen mode

And handle deliveries with a few lines of Flask:

from flask import Flask, request

app = Flask(__name__)

@app.post("/webhooks/nylas")
def nylas_webhook():
    payload = request.get_json()
    if payload.get("type") == "message.created":
        msg = payload["data"]["object"]
        print(f"New mail on {msg['grant_id']}: {msg['subject']}")
    return "", 200
Enter fullscreen mode Exit fullscreen mode

The payload is identical in shape to message.created for a connected grant — the docs' example carries subject, from, to, date, and snippet under data.object. If your app mixes account types, the documented discriminator is the grant's provider field, which reports "nylas" for agent grants.

Inbound attachments come through as IDs on the message; download the bytes from the attachments endpoint, passing the message ID as a query parameter:

attachment = requests.get(
    f"{BASE}/v3/grants/{grant_id}/attachments/{attachment_id}/download",
    headers=HEADERS,
    params={"message_id": message_id},
)
with open("invoice.pdf", "wb") as f:
    f.write(attachment.content)
Enter fullscreen mode Exit fullscreen mode

Size and count limits on inbound attachments are governed by your plan and the grant's policy — the knobs are limit_attachment_size_limit, limit_attachment_count_limit, and limit_attachment_allowed_types on the policy object.

Step 3: send

Outbound is the same /messages/send endpoint used for any connected grant:

requests.post(
    f"{BASE}/v3/grants/{grant_id}/messages/send",
    headers=HEADERS,
    json={
        "subject": "Hello from my Agent Account",
        "body": "This message was sent by a Nylas Agent Account.",
        "to": [{"email": "you@yourdomain.com", "name": "You"}],
    },
)
Enter fullscreen mode Exit fullscreen mode

What the recipient sees is a normal email from the agent's address — no "sent via" branding, no relay footer.

Step 4: prove the loop

The docs' end-to-end test, scripted: send a message from your personal account to the agent's address, confirm it shows up (webhook or the polling snippet), then fire the send call and watch the reply land back in your own inbox. Once that round trip works, you have a mailbox your Python code fully owns.

Step 5: the calendar, since it's already there

Every account ships with a primary calendar, driven by the same grant_id. Hosting a meeting is one more requests.post — with notify_participants=true, each participant gets a real invitation from the agent's address:

requests.post(
    f"{BASE}/v3/grants/{grant_id}/events",
    headers=HEADERS,
    params={"calendar_id": "primary", "notify_participants": "true"},
    json={
        "title": "Product demo",
        "when": {"start_time": 1744387200, "end_time": 1744390800},
        "participants": [{"email": "alice@example.com"}],
    },
)
Enter fullscreen mode Exit fullscreen mode

And when someone invites the agent, it responds through send-rsvp with yes, no, or maybe:

requests.post(
    f"{BASE}/v3/grants/{grant_id}/events/{event_id}/send-rsvp",
    headers=HEADERS,
    params={"calendar_id": "primary"},
    json={"status": "yes"},
)
Enter fullscreen mode Exit fullscreen mode

Everything travels over standard iCalendar, so Google Calendar, Microsoft 365, and Apple Calendar treat the agent as a normal participant — its RSVP is visible to every attendee.

A few gotchas before you script this

  • Be deliberate about workspaces in production. The default workspace is a fine landing zone for a test account, but quotas, spam settings, and mail rules all flow from the workspace — passing workspace_id explicitly is the difference between an agent with guardrails and one running at plan maximums.
  • The trial domain is for testing. *.nylas.email addresses work instantly, but production agents belong on your own domain — ideally a dedicated subdomain like agents.yourcompany.com so agent traffic carries its own sender reputation.
  • Branch on provider, not on the grant ID. If your application mixes agent grants with connected Gmail or Outlook grants, the documented discriminator is the grant's provider field — agent grants report "nylas". Hard-coding grant IDs into your dispatch logic falls apart the moment you provision account number two.

The obvious next move is dropping an LLM into the webhook handler: classify the message, draft a reply, call send. If you build that — or hit any rough edge while trying — what's the first job you'd hand a mailbox that no human has to log into?

Top comments (0)