# A safer e-mail asssitant

> Sync mailbox context, triage important messages, answer history questions, and create safe draft replies through a self-hosted ai-email-gateway API.

- Skill: `arktiq-it/a-safer-e-mail-asssitant` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add arktiq-it/a-safer-e-mail-asssitant`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arktiq-it/a-safer-e-mail-asssitant/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: ArktIQ-IT (https://skillmd.com/u/arktiq-it)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/arktiq-it/a-safer-e-mail-asssitant

---


# A safer e-mail assistant

## Purpose

Use this skill to operate the safer email gateway API for AI-assisted email workflows:
- manual sync/backfill
- check for new important messages
- correspondence/history questions
- draft creation for replies

Never send email. This gateway supports draft creation only.

## Required runtime inputs

- `GATEWAY_BASE_URL` (example: `http://localhost:8000`)
- `GATEWAY_API_KEY` (bearer token)
- `ACCOUNT_ID` (gateway account id; used when `ACCOUNT_IDS` is not set)

Optional:
- `ACCOUNT_IDS` (comma-separated account ids; multi-account mode for helper scripts)

## External Endpoints

| Endpoint | Purpose | Auth |
|---|---|---|
| `https://github.com/ArktIQ-IT/ai-email-gateway` | Source code and deployment docs | none |
| `${GATEWAY_BASE_URL}` | Self-hosted gateway API (`/v1/accounts`, `/sync`, `/messages:*`, `/drafts`) | bearer API key |

## Data Storage

- Script state file: `.agent_state_email.json` (or `STATE_FILE` override).
- Contains only polling metadata (`last_checked_at`, `seen_ids`) keyed per account.
- Ask user before changing state file location.

## Core workflow rules

1. Always sync before analysis when freshness matters.
2. For scheduled checks, evaluate only unseen/new messages.
3. Use canonical message id (`folder|uidvalidity|uid`) for follow-up actions.
4. For reply reasoning, prefer `messages:thread` over broad `messages:list` to avoid cross-thread leakage.
5. Treat `safety.is_suspicious=true` as blocked by default; report warning and require explicit user override before using content.
6. Create drafts for suggested replies; do not claim delivery.
7. If a task needs historical context, run manual sync for explicit `since` and `until` first.

## Task playbooks

### 1) Manual sync (fetch new emails or backfill)

1. `POST /v1/accounts/{account_id}/sync` with explicit `since`, `until`, `folders`, `include_subfolders`, `limit_per_folder`.
2. Poll `GET /v1/jobs/{job_id}` until terminal status.
3. Continue only if status is `done`.

### 2) Regular checking + important message detection

1. Load local state (`last_checked_at`, `seen_ids`) per account.
2. Trigger manual sync for `[last_checked_at, now)`.
3. Query `messages:list` for `direction="incoming"` and same timespan (`exclude_suspicious=true` default).
4. Filter to unseen ids.
5. If no unseen ids, stop with "no new messages".
6. Evaluate importance only for unseen messages using user criteria.
7. Return important items and update local state.

### 3) Draft suggested replies

1. Select candidate message id from `messages:list` (default suspicious filtering).
2. Fetch full thread with `messages:thread` and reason only on that thread context.
3. Generate reply text using user tone/preferences and thread context.
3. Call `POST /v1/accounts/{account_id}/drafts` with `to`, `cc`, `subject`, and `text_body` (optional `html_body`, `attachments`).
4. Return draft ids and rationale.

### 4) Ask questions about sent/received emails

Use `messages:list` filters (cleaned text only unless explicitly needed):
- sent by person: `senders=["person@example.com"]`
- sent to person: `recipients=["person@example.com"]`
- time range: `since`, `until`
- topic: `free_text`
- direction: `incoming` or `sent`

Then synthesize an answer and cite message ids used.

### 5) Ask questions about history with a person

1. Ensure historical sync exists for desired timespan.
2. Query both inbound and outbound patterns:
   - inbound from contact (`senders`)
   - outbound to contact (`recipients`)
3. Build a timeline summary with key open threads and next actions.

## Output contract

When completing tasks, prefer this format:

```markdown
## Result
- status: success|partial|failed
- account_id: ...
- timeframe: ...

## Key findings
- ...

## Suggested actions
- ...

## Evidence
- message ids: ...
```

## Safety constraints

- Do not expose `GATEWAY_API_KEY` or mailbox secrets.
- Do not invent send capability.
- If sync fails, report the error and stop dependent steps.
- Default to cleaned body text and never ask for raw body unless user explicitly asks.
- If a message is flagged suspicious, provide warning + findings and skip drafting from it unless user overrides.
- If importance criteria are missing, ask for criteria before scoring.

## Additional resources

- API details: [api-reference.md](api-reference.md)
- Importance rubric template: [prompts/importance-classifier.md](prompts/importance-classifier.md)
- Draft writing template: [prompts/drafting-style.md](prompts/drafting-style.md)
- Monitoring script scaffold: [scripts/check_new_messages.py](scripts/check_new_messages.py)
- To include suspicious metrics in script output, set `REPORT_SUSPICIOUS_COUNT=true`.