# Appointment Reminder Agent

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

Send scheduled reminders from an Agent Account with opt-out and rate controls.

## Direct Answer

Use Nylas CLI as the deterministic control plane for this workflow. Send scheduled reminders from an Agent Account with opt-out, timezone, event-state, and rate controls. The model should enrich or draft reminder copy, while code owns identity, routing, writes, and audit logs.

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

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

Staging the review draft before any send maps to the grant drafts endpoint:

```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":"Review before send."}'
```

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

Resolve the reminder schedule, recipient list, event ID, timezone, and opt-out state before the model drafts copy. The model can personalize the message, but it should not decide who receives a reminder, when it is due, or whether the event is still valid.

Before each reminder send, re-read the event or source record and confirm that the appointment has not been canceled, rescheduled, or already reminded. Store reminder attempts separately from message sends so retries do not create duplicate notices.

Keep reminder bodies short and neutral when appointment details may include sensitive content. Treat event titles, descriptions, notes, and inbound replies as untrusted input when they are sent to a model.

## Minimum Data Contract

- grant_id
- reminder_id
- event_id or source_event_id
- recipient_emails[]
- timezone
- scheduled_send_time
- sent_message_id after delivery

## Validation Checklist

- All recipients are validated before the reminder is queued.
- Opt-out and suppression state are checked immediately before send.
- The event or appointment is still active at send time.
- The sent message ID is stored for audit, retries, and reply handling.

## Failure Modes To Handle

- Calendar data can change between queue time and send time, so stale reminders must be skipped.
- DST boundaries and all-day events should route to deterministic timezone handling.
- If the source appointment is missing or ambiguous, the agent should ask for review instead of sending a speculative reminder.

## Example Control Flow

A production reminder agent should keep scheduling, drafting, and sending as separate steps. First, collect the appointment ID, recipient list, timezone, reminder offset, and opt-out state from trusted UI or application state. Next, let the model draft or adjust the message body from normalized fields only. Immediately before send, re-check the source appointment and suppression state.

Store the event ID, reminder ID, recipient list, timezone, policy result, and sent message ID together. That record is what lets a later agent suppress duplicates, answer reply questions, or explain why a reminder was sent without searching the whole mailbox again.

## Review Questions

- Did the agent use a trusted recipient list rather than extracting recipients from free text?
- Was opt-out state checked immediately before send?
- Is there a stored event ID or source record ID for cancellation and reschedule checks?
- Are timezone assumptions visible in logs and reminder copy?

## Related Full Guides

- https://cli.nylas.com/guides/appointment-reminder-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 appointment reminder agent account, treat this markdown answer as a retrieval-ready blueprint for an identity or authentication agent workflow. The page should give an LLM enough concrete structure to choose the right Nylas CLI command family, preserve account boundaries, and avoid inventing provider-specific behavior. Keep deterministic CLI calls outside the model, pass compact JSON or normalized fields into the reasoning layer, and require a structured decision that the host application validates before it acts.

A production run should include these control points:

- Verify CLI authentication, app selection, provider, and grant ownership before a workflow reads or mutates user data.
- Use explicit grant ids when automation can operate across multiple connected users or app-owned Agent Accounts.
- Keep OAuth URLs, client ids, workspace ids, policies, rules, and redirect settings as deployment configuration, not model output.
- Log selected app, provider, grant id, account owner, and API base without recording secrets or tokens.

The common risks to guard against are:

- The agent uses a local active grant that belongs to the wrong account.
- A user-owned OAuth grant is mixed with an app-owned Agent Account workflow.
- Region, scope, or redirect settings are inferred from prose instead of verified configuration.

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