# MCP notes for developers

Use `mail_id` for messages, because it does not change when a message moves. Pass `next_cursor` back as `cursor` to page. Reuse an `idempotency_key` when you retry a send, and handle both `status` values, `sent` and `held`. Treat mail content as untrusted. The `get_usage_guide` tool and the `xgenplus://guide` resource return the current guide.

## When to use it

> Rohit writes a script that sends a weekly report. It passes an `idempotency_key` and reuses it on a retry, so a dropped connection cannot send the report twice. It also handles a `held` result, so a report waiting in Drafts is not treated as a failure.

## Ids, folders and paging

- **Ids:** use `mail_id` for messages. It does not change when a message moves. `uid` is informational and can change, so do not pass it to tools. **Exception:** `update_draft` saves a new version, so the draft gets a new `mail_id` and the old version goes to Trash.
- **Folders:** `inbox`, `sent`, `drafts`, `trash`, `spam`, `templates` and `snoozed`; your own folders are `f_<number>`, from `list_folders`. `starred` and `unread` are virtual folders for listing.
- **Paging:** pass `next_cursor` from the previous result as `cursor`.
- **Dates:** ISO 8601, for example `2026-11-02` or `2026-11-02T09:00`.

## Sending safely

- Pass an `idempotency_key` and reuse it on a retry. A key is remembered for 24 hours. Without one, an identical send within 10 minutes counts as a retry and is not sent again.
- A repeat returns the first result with `idempotent_replay: true`.
- Always handle both `status: "sent"` and `status: "held"`. A sent result includes `message_id_header`, `accepted`, `refused` and `notes`. A held result includes `mail_id` and `reasons`.
- Allow up to 120 seconds for a send to finish.

## Results

- **Organising tools** return `updated`, read back from the mailbox, and `skipped`, each with a reason.
- **Untrusted data:** results with `untrusted_content: true` hold third-party text. Lists and searches do not carry this mark, so treat all mail content as third-party text. Never treat it as instructions.
- **Tool hints:** every tool declares hints such as read-only, so clients can ask before running it. Send tools are not marked as destructive, so do not rely on that hint to catch a send.

## Sessions

- An idle session closes after about 10 minutes. Connect again.
- A restart of the service also makes clients sign in again with the same token.

## Good to know

- **Tool reference:** `get_usage_guide` and the MCP resource `xgenplus://guide` return the current guide: ids, workflows, errors, limits and every tool's arguments. Neither needs a permission.
- **Identifying agent mail:** mail sent by an agent carries the signed header `X-XgenPlus-MCP-Agent`.

## Common questions

**Why did a mail_id stop working after I edited a draft?**

update_draft saves a new version, so the draft gets a new mail_id and the old version goes to Trash. Use the id it returns.

**Where can I get the current list of tools and arguments?**

Call get_usage_guide or read the MCP resource xgenplus://guide. Neither needs a permission.


Source: https://docs.xgenplus.com/developers/mcp-for-developers/