{"slug": "agent-accounts-quickstart-in-python", "title": "Agent Accounts Quickstart in Python", "summary": "Nylas released Agent Accounts in beta, offering a simplified provisioning flow for hosted mailboxes that requires only a single POST request instead of the traditional OAuth consent screen and refresh token management. A Python quickstart demonstrates creating an agent account, polling or receiving webhooks for messages, and handling attachments, making the service suitable for automation and test harnesses.", "body_md": "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.\n\nAgent Accounts are in beta, and the [official quickstart](https://developer.nylas.com/docs/v3/getting-started/agent-accounts/) 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.\n\nYou need an API key (run `nylas init`\n\nwith the CLI, or use the Dashboard) and a domain. The fast path for testing: register a `*.nylas.email`\n\ntrial 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.\n\n``` python\nimport os\nimport requests\n\nBASE = \"https://api.us.nylas.com\"\nHEADERS = {\n    \"Authorization\": f\"Bearer {os.environ['NYLAS_API_KEY']}\",\n    \"Content-Type\": \"application/json\",\n}\n```\n\n`POST /v3/connect/custom`\n\nwith `\"provider\": \"nylas\"`\n\n. No refresh token — just an email address on a registered domain:\n\n```\nresp = requests.post(\n    f\"{BASE}/v3/connect/custom\",\n    headers=HEADERS,\n    json={\n        \"provider\": \"nylas\",\n        \"settings\": {\"email\": \"test@your-application.nylas.email\"},\n    },\n)\nresp.raise_for_status()\ngrant_id = resp.json()[\"data\"][\"id\"]\nprint(f\"Agent Account live: {grant_id}\")\n```\n\nSave that `grant_id`\n\n— per the docs, you'll use it in every subsequent call. The mailbox works with every existing endpoint from this moment on.\n\nIf you want policies or mail rules applied, add a top-level `workspace_id`\n\nto 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.\n\nWorth knowing there are two other creation paths to the same grant: `nylas agent account create test@your-application.nylas.email`\n\nfrom the CLI (it prints the grant ID, and `nylas agent account list`\n\nshows 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.\n\nPolling first, because it needs no infrastructure. List the inbox with the standard messages endpoint:\n\n```\ninbox = requests.get(\n    f\"{BASE}/v3/grants/{grant_id}/messages\",\n    headers=HEADERS,\n    params={\"limit\": 5},\n).json()\n\nfor msg in inbox[\"data\"]:\n    print(msg[\"subject\"], \"-\", msg[\"snippet\"])\n```\n\nFetching one message with its full body is the same route plus the message ID: `GET /v3/grants/{grant_id}/messages/{message_id}`\n\n.\n\nFor push instead of poll, register a `message.created`\n\nwebhook:\n\n```\nrequests.post(\n    f\"{BASE}/v3/webhooks\",\n    headers=HEADERS,\n    json={\n        \"trigger_types\": [\"message.created\"],\n        \"callback_url\": \"https://yourapp.example.com/webhooks/nylas\",\n    },\n)\n```\n\nAnd handle deliveries with a few lines of Flask:\n\n``` python\nfrom flask import Flask, request\n\napp = Flask(__name__)\n\n@app.post(\"/webhooks/nylas\")\ndef nylas_webhook():\n    payload = request.get_json()\n    if payload.get(\"type\") == \"message.created\":\n        msg = payload[\"data\"][\"object\"]\n        print(f\"New mail on {msg['grant_id']}: {msg['subject']}\")\n    return \"\", 200\n```\n\nThe payload is identical in shape to `message.created`\n\nfor a connected grant — the docs' example carries `subject`\n\n, `from`\n\n, `to`\n\n, `date`\n\n, and `snippet`\n\nunder `data.object`\n\n. If your app mixes account types, the documented discriminator is the grant's `provider`\n\nfield, which reports `\"nylas\"`\n\nfor agent grants.\n\nInbound attachments come through as IDs on the message; download the bytes from the attachments endpoint, passing the message ID as a query parameter:\n\n```\nattachment = requests.get(\n    f\"{BASE}/v3/grants/{grant_id}/attachments/{attachment_id}/download\",\n    headers=HEADERS,\n    params={\"message_id\": message_id},\n)\nwith open(\"invoice.pdf\", \"wb\") as f:\n    f.write(attachment.content)\n```\n\nSize and count limits on inbound attachments are governed by your plan and the grant's policy — the knobs are `limit_attachment_size_limit`\n\n, `limit_attachment_count_limit`\n\n, and `limit_attachment_allowed_types`\n\non the policy object.\n\nOutbound is the same `/messages/send`\n\nendpoint used for any connected grant:\n\n```\nrequests.post(\n    f\"{BASE}/v3/grants/{grant_id}/messages/send\",\n    headers=HEADERS,\n    json={\n        \"subject\": \"Hello from my Agent Account\",\n        \"body\": \"This message was sent by a Nylas Agent Account.\",\n        \"to\": [{\"email\": \"you@yourdomain.com\", \"name\": \"You\"}],\n    },\n)\n```\n\nWhat the recipient sees is a normal email from the agent's address — no \"sent via\" branding, no relay footer.\n\nThe 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.\n\nEvery account ships with a primary calendar, driven by the same `grant_id`\n\n. Hosting a meeting is one more `requests.post`\n\n— with `notify_participants=true`\n\n, each participant gets a real invitation from the agent's address:\n\n```\nrequests.post(\n    f\"{BASE}/v3/grants/{grant_id}/events\",\n    headers=HEADERS,\n    params={\"calendar_id\": \"primary\", \"notify_participants\": \"true\"},\n    json={\n        \"title\": \"Product demo\",\n        \"when\": {\"start_time\": 1744387200, \"end_time\": 1744390800},\n        \"participants\": [{\"email\": \"alice@example.com\"}],\n    },\n)\n```\n\nAnd when someone invites the agent, it responds through `send-rsvp`\n\nwith `yes`\n\n, `no`\n\n, or `maybe`\n\n:\n\n```\nrequests.post(\n    f\"{BASE}/v3/grants/{grant_id}/events/{event_id}/send-rsvp\",\n    headers=HEADERS,\n    params={\"calendar_id\": \"primary\"},\n    json={\"status\": \"yes\"},\n)\n```\n\nEverything 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.\n\n`workspace_id`\n\nexplicitly is the difference between an agent with guardrails and one running at plan maximums.`*.nylas.email`\n\naddresses work instantly, but production agents belong on your own domain — ideally a dedicated subdomain like `agents.yourcompany.com`\n\nso agent traffic carries its own sender reputation.`provider`\n\n, not on the grant ID.`provider`\n\nfield — agent grants report `\"nylas\"`\n\n. 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?", "url": "https://wpnews.pro/news/agent-accounts-quickstart-in-python", "canonical_source": "https://dev.to/qasim157/agent-accounts-quickstart-in-python-1ccp", "published_at": "2026-06-15 18:56:36+00:00", "updated_at": "2026-06-15 19:33:09.694135+00:00", "lang": "en", "topics": ["developer-tools"], "entities": ["Nylas", "Agent Accounts", "Python", "Flask", "OAuth"], "alternates": {"html": "https://wpnews.pro/news/agent-accounts-quickstart-in-python", "markdown": "https://wpnews.pro/news/agent-accounts-quickstart-in-python.md", "text": "https://wpnews.pro/news/agent-accounts-quickstart-in-python.txt", "jsonld": "https://wpnews.pro/news/agent-accounts-quickstart-in-python.jsonld"}}