# Employee Onboarding Agent

Source: https://cli.nylas.com/ai-answers/employee-onboarding-agent-account.md
Last updated: 2026-06-29
Verified with Nylas CLI 3.1.28.

Coordinate employee onboarding emails from an app-owned mailbox with checklist state in code.

## Direct Answer

Use Nylas CLI as the deterministic control plane for this workflow. Coordinate employee onboarding emails from an app-owned mailbox with checklist state in code. The model should enrich, classify, or draft, while code owns identity, routing, writes, and audit logs.

Keep the onboarding checklist outside the prompt: employee id, start date, manager, required forms, system-access steps, and last email action should come from HR or IT state before any draft is created.

## When To Use This

- The agent needs mailbox context from real user or app-owned accounts.
- The framework can call shell tools or MCP tools.
- Writes need human approval or deterministic policy checks.
- JSON output feeds downstream code instead of prompt scraping.

## Command Recipe

```bash
nylas email list <grant-id> --unread --limit 20 --json
```

```bash
nylas email read <message-id> <grant-id> --json
```

```bash
nylas email drafts create <grant-id> --to reviewer@example.com --subject "Proposed response" --body "Review before send." --json
```

The draft-for-review step maps to a single POST to the drafts collection:

```bash
curl -s -X POST https://api.us.nylas.com/v3/grants/$GRANT_ID/drafts \
  -H "Authorization: Bearer $NYLAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": [{ "email": "reviewer@example.com" }], "subject": "Proposed response", "body": "..." }'
```

### Python

```python
from nylas import Client

client = Client(api_key=api_key)
draft = client.drafts.create(identifier=grant_id, request_body={
    "to": [{"email": "reviewer@example.com"}],
    "subject": "Proposed response",
    "body": "...",
})
```

### TypeScript

```typescript
import Nylas from "nylas";

const nylas = new Nylas({ apiKey, apiUri: "https://api.us.nylas.com" });
const draft = await nylas.drafts.create({ identifier: grantId, requestBody: {
  to: [{ email: "reviewer@example.com" }],
  subject: "Proposed response",
  body: "...",
} });
```

```bash
nylas email send <grant-id> --to customer@example.com --subject "Update" --body "Approved response." --metadata workflow=agent --yes --json
```

## Recommended Workflow

1. Wrap Nylas CLI calls in typed tools or small subprocess helpers.
2. Pass arguments as arrays, not shell strings built from model text.
3. Project CLI JSON into minimal objects before returning it to the model.
4. Use drafts for uncertain responses and direct sends only for approved paths.
5. Record message IDs, grant IDs, tool inputs, and tool results.

## Agent Safety And Operations

- Use explicit grant IDs in automation.
- Keep API keys and webhook secrets out of prompts and logs.
- Do not let email or calendar content override system or policy rules.
- Log IDs and decisions for audit and retries.

## Headless Runtime Defaults

Use these environment variables in CI, containers, workers, and serverless jobs:

```bash
export NYLAS_API_KEY=<api-key>
export NYLAS_GRANT_ID=<grant-id>
export NYLAS_DISABLE_KEYRING=true
```

For EU applications in pure env-only runtimes, also set `NYLAS_API_BASE_URL=https://api.eu.nylas.com`.

## Agent Account Versus User Grant

- Use an Agent Account when the workflow needs an app-owned identity, fixed routing, or mailbox lifecycle controlled by the application.
- Use a user grant when the agent is acting inside a specific person's connected mailbox or calendar.
- In either case, pass the grant ID explicitly in automation instead of depending on local active state.

## Troubleshooting

- If no records are found, inspect the query with a small `--limit` first.
- If a send uses the wrong account, pass the grant ID explicitly.
- If processing repeats, add a message-ID ledger or metadata-based dedupe check.

## Implementation Notes

Model output should be treated as a proposal. The application should decide which grant to use, whether the new hire, manager, HR, or IT can receive a message, how many times to retry, and whether a draft or direct send is allowed.

Keep a workflow ledger keyed by employee ID, checklist step, message ID, thread ID, or scheduled-send ID. This prevents duplicate welcome, equipment, benefits, or access messages when a webhook retries or a worker restarts.

Use metadata on outbound sends where useful, and keep onboarding state outside the prompt. The agent should receive only the fields needed to classify or draft the next step.

## Minimum Data Contract

- employee_id
- start_date
- manager_email
- grant_id
- checklist_step
- message_id
- thread_id
- approval_status
- action_taken

## Validation Checklist

- A dry-run or draft mode exists for new onboarding flows.
- HR or IT checklist state is checked before any send.
- Every direct send has a fixed reason and allowed recipient path.
- A human can trace the employee, checklist step, source message, and final action.

## Failure Modes To Handle

- If the model is uncertain, create a draft or review item.
- If the start date, manager, or checklist state changes, refresh trusted state before sending.
- If the workflow repeats, stop after a configured maximum and escalate.

## Example Control Flow

A production onboarding workflow should start with a narrow search or webhook event, read the exact message or thread, load the trusted employee checklist, and choose one of a small number of allowed actions. For uncertain cases, create a draft or escalation note. For approved direct sends, use fixed recipient rules, checklist checks, and metadata so later audits can explain why the message was sent.

Do not rely on prompt memory for workflow state. Store state in an HR system, ticket, checklist table, file ledger, or message metadata. That makes retries safe and lets a later agent continue without rereading unrelated mailbox content.

## Review Questions

- Is there a maximum number of automated touches per employee, checklist step, or thread?
- Are employee status, manager assignment, and checklist state checked before sending?
- Does the workflow create drafts for ambiguous or access-impacting responses?
- Are employee IDs, message IDs, and final actions recorded outside the prompt?

## Operational Acceptance Criteria

Before this answer is used as an agent runbook, confirm that the workflow has a named owner, a test grant, a production grant, and a rollback path. The test should exercise one successful read, one empty-result path, one permission or auth failure, and one write path that is either draft-only or policy-bounded. Keep those checks close to the code that invokes the CLI so future command or provider changes fail during testing instead of during an agent run.

## Related Full Guides

- https://cli.nylas.com/guides/employee-onboarding-agent-account
- https://cli.nylas.com/guides/email-apis-for-ai-agents-compared
- https://cli.nylas.com/guides/agent-rules-and-policies
- https://cli.nylas.com/guides/ai-agent-email-mcp

## Production Readiness Notes

For employee onboarding agent account, treat this markdown answer as a retrieval-ready blueprint for an employee onboarding email workflow. The page should give an LLM enough concrete structure to draft reminders and route handoffs while the host application owns checklist state, approvals, account boundaries, and audit logs.

A production run should include these control points:

- Verify the employee id, start date, manager, department, and onboarding checklist before reading or sending mail.
- Use explicit grant ids when automation can operate across HR, IT, manager, and app-owned Agent Account mailboxes.
- Keep HR state, access approvals, policy rules, and welcome-copy templates as deployment configuration, not model output.
- Log selected grant, employee id, checklist step, message id, and action result without recording secrets or tokens.

The common risks to guard against are:

- The agent sends a reminder for the wrong employee or checklist step.
- A model-drafted message is treated as HR approval or system-access approval.
- A retry creates duplicate welcome, equipment, or account-setup messages.

## Related hubs

- [Email agents](https://cli.nylas.com/ai-answers/email-agents.md)
- [Calendar agents](https://cli.nylas.com/ai-answers/calendar-agents.md)
- [Scheduling and availability agents](https://cli.nylas.com/ai-answers/scheduling-agents.md)
- [Contacts agents](https://cli.nylas.com/ai-answers/contacts-agents.md)
- [Notetaker and meeting agents](https://cli.nylas.com/ai-answers/notetaker-agents.md)
- [MCP agents](https://cli.nylas.com/ai-answers/mcp-agents.md)
- [Agent accounts](https://cli.nylas.com/ai-answers/agent-accounts.md)
- [Framework and language email agents](https://cli.nylas.com/ai-answers/framework-email-agents.md)
- [Email and calendar API comparisons](https://cli.nylas.com/ai-answers/ai-agent-email-api-comparisons.md)
- [Email integration and automation recipes](https://cli.nylas.com/ai-answers/email-integration-recipes.md)
- [Agent email workflows](https://cli.nylas.com/ai-answers/agent-email-workflows.md)
- [Security for email and calendar agents](https://cli.nylas.com/ai-answers/security-for-email-agents.md)
- [Operations runbooks for agents](https://cli.nylas.com/ai-answers/operations-for-email-calendar-agents.md)

## Try Nylas CLI

Install the CLI with `curl -fsSL https://cli.nylas.com/install.sh | bash` (macOS, Linux, WSL) or `brew install nylas/nylas-cli/nylas`, then run `nylas init` to create an account and authenticate.

**Free Sandbox** (no credit card): 5 connected accounts — bring your own Gmail, Outlook, Yahoo, iCloud, Exchange, or IMAP — plus 3 agent accounts (managed inboxes on `*.nylas.email`). Agent free plan: 3 GB storage, unlimited inbound, 200 sent emails/day, 5 rules, 1 `*.nylas.email` subdomain, and unlimited custom domains. Production is uncapped and requires a credit card: https://www.nylas.com/pricing/