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

Source: https://developer.nylas.com/docs/cookbook/agent-accounts/sign-up-for-a-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 finishes onboarding on its own. This recipe is the end-to-end flow.

> **Info:** 
> **Prerequisites.** You need a Nylas API key, a domain registered with Nylas (trial `*.nylas.email` subdomains work for prototyping — see [Setup domains](/docs/v3/agent-accounts/dns-provider-setup/)), and a publicly reachable HTTPS endpoint for the `message.created` webhook. For local development, [VS Code port forwarding](https://code.visualstudio.com/docs/editor/port-forwarding) or [Hookdeck](https://hookdeck.com/) work well. The CLI commands below assume you've installed and authenticated the [Nylas CLI](https://cli.nylas.com/).

## 1. Provision the Agent Account

The quickest path is the [Nylas CLI](https://cli.nylas.com/):

```bash
nylas agent account create signup-agent@agents.yourdomain.com
```

The CLI prints the new grant ID — save it as `AGENT_GRANT_ID`. If you prefer the API, use [`POST /v3/connect/custom`](/docs/reference/api/manage-grants/byo_auth/):

```bash
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": "signup-agent@agents.yourdomain.com"
    }
  }'
```

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

From the CLI:

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

Or through the API:

```bash
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

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

```js
// 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: "signup-agent@agents.yourdomain.com",
    name: "Automation Agent",
  }),
});
```

## 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.

```js
// 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](/docs/cookbook/agent-accounts/extract-otp-code/).

## 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:

```bash
nylas agent account delete signup-agent@agents.yourdomain.com --yes
```

Or through the API:

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

## Things to know

- **Attach a strict policy.** Limit inbound acceptance to the domains you actually expect mail from by pairing a [list](/docs/v3/agent-accounts/policies-rules-lists/) 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 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.
- **Don't ship per-run agents without tear-down.** Inactive grants accumulate. If you provision a fresh Agent Account per signup, delete it on completion or fail.

## Next steps

- [Extract an OTP or 2FA code from an agent's inbox](/docs/cookbook/agent-accounts/extract-otp-code/) — the paired recipe for code-based verification
- [Handle email replies in an agent loop](/docs/cookbook/agent-accounts/handle-replies/) — for services that send follow-up confirmations
- [Agent Accounts overview](/docs/v3/agent-accounts/) — the full product doc
- [Policies, Rules, and Lists](/docs/v3/agent-accounts/policies-rules-lists/) — constrain what the inbox accepts
- [Using webhooks with Nylas](/docs/v3/notifications/) — signature verification and retry handling