Skip to content
Skip to main content

How to sign an agent up for a third-party service

AI agents often need to sign up for the services they work with — a research agent needs a developer account on a data source, a QA agent registers for a SaaS every test run, a purchasing agent needs a buyer profile on a marketplace. The hard part is receiving the verification email without routing through a human inbox.

Nylas Agent Accounts solve this directly: the agent gets its own mailbox, signs up with that address, catches the verification email via webhook, and completes the signup on its own. This recipe walks through the end-to-end flow.

What you’ll build

Section titled “What you’ll build”
  1. Provision an Agent Account at [email protected].
  2. Subscribe to message.created so inbound mail fires a webhook.
  3. Have the agent submit the signup form at the target service using its Agent Account address.
  4. Parse the verification email — either click the confirmation link or extract a code.
  5. Return the outcome (logged in / confirmed) to whatever called the agent.

Before you begin

Section titled “Before you begin”

1. Provision the Agent Account

Section titled “1. Provision the Agent Account”

The quickest path is the Nylas CLI:

nylas agent account create [email protected]

The CLI prints the new grant ID — save it as AGENT_GRANT_ID. If you prefer the API, use POST /v3/connect/custom:

curl --request POST \
  --url "https://api.us.nylas.com/v3/connect/custom" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "provider": "nylas",
    "settings": {
      "email": "[email protected]"
    }
  }'

One Agent Account can be reused across many signup runs, or you can provision a fresh one per run and tear it down afterwards.

2. Subscribe to inbound mail

Section titled “2. Subscribe to inbound mail”

From the Nylas CLI:

nylas webhook create \
  --url https://youragent.example.com/webhooks/signup \
  --triggers message.created

Or through the API:

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.created"],
    "webhook_url": "https://youragent.example.com/webhooks/signup",
    "description": "Agent signup verification"
  }'

Nylas fires message.created within a second or two of mail arriving. The payload carries the Message object’s summary fields; fetch the full body from the API when you need it.

3. Submit the signup form

Section titled “3. Submit the signup form”

Use the Agent Account address when you fill in the form — whatever the target service sends a verification email to.

// Whatever flow makes sense for the target service:
// - a direct API call, if they expose one
// - a headless browser step (Playwright / Puppeteer)
// - a simple fetch POST, as below
await fetch("https://saas-you-care-about.example.com/signup", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "[email protected]",
    name: "Automation Agent",
  }),
});

4. Handle the verification email

Section titled “4. Handle the verification email”

When the target service’s verification email lands in the Agent Account, your webhook handler gets the notification. Fetch the body, find the confirmation link, and follow it.

// Node.js / Express handler sketch
app.post("/webhooks/signup", async (req, res) => {
  // (Verify X-Nylas-Signature here — see /docs/v3/notifications/.)
  res.status(200).end();


  const event = req.body;
  if (event.type !== "message.created") return;


  const { grant_id, id: messageId, from } = event.data.object;
  if (grant_id !== AGENT_GRANT_ID) return;


  // Only react to mail from the service you signed up with.
  const sender = from[0]?.email ?? "";
  if (!sender.endsWith("@saas-you-care-about.example.com")) return;


  // Pull the full body.
  const resp = await fetch(
    `https://api.us.nylas.com/v3/grants/${AGENT_GRANT_ID}/messages/${messageId}`,
    { headers: { Authorization: `Bearer ${NYLAS_API_KEY}` } },
  );
  const message = (await resp.json()).data;


  // Find the confirmation link. Two common patterns:
  //   1. A specific-looking URL in the HTML body
  //   2. A button/link labeled "Confirm", "Verify", etc.
  const match = /https:\/\/saas-you-care-about\.example\.com\/confirm\?token=[^"\s<]+/.exec(
    message.body,
  );
  if (!match) return;


  // Visit the confirmation URL to complete signup.
  await fetch(match[0]);
});

For more complex flows (multi-step confirmation, captchas, OAuth redirects), drop in a headless browser on this step and have it follow the link instead of a raw fetch.

If the service sends an OTP or 2FA code instead of a link, the parsing shape is the same — see Extract an OTP or 2FA code from an agent’s inbox.

5. Tear down (optional)

Section titled “5. Tear down (optional)”

For per-run agents, delete the grant when you’re done so you’re not accumulating inactive accounts. From the CLI:

nylas agent account delete [email protected] --yes

Or through the API:

curl --request DELETE \
  --url "https://api.us.nylas.com/v3/grants/<AGENT_GRANT_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

Keep in mind

Section titled “Keep in mind”
  • Attach a strict policy. Limit inbound acceptance to the domains you actually expect mail from by pairing a list of allowed from.domain values with a block rule for everything else. That keeps the inbox clean even if the test address leaks.
  • Don’t trust the first message that arrives. Some services send a “Welcome” email before the verification email. Match the sender and the expected URL pattern — both — before clicking anything.
  • Respect the service’s ToS. Programmatic signup is fine for your own testing and for first-party integrations; scraping third parties is a different conversation. Nylas doesn’t enforce anything here, but your legal team will.
  • Rate limits matter more than you think. The default Agent Account send quota is 100 messages per day; inbound is generous but not infinite. If you’re running a large test matrix, provision multiple grants rather than reusing one.

What’s next

Section titled “What’s next”