MarkRelay
Documentation navigation

AI Agent Skill

Give an AI agent its own business mailbox—or controlled access to an existing one. MarkRelay provides a compact tool contract the agent can discover and use for sending, triage, replies, and attachments.

Create a safe agent mailbox

  1. Create a dedicated mailbox such as agent@example.com.
  2. Create a member identity for the agent owner or integration.
  3. Grant only the mailbox or domain the workflow needs.
  4. Create a named personal API key with selected-mailbox scope.
  5. Store the key in the agent runtime's secret manager.

Install the skill

Every deployment serves two agent-friendly resources:

  • https://<your-deployment>/llms.txt — concise API instructions for model context;
  • https://<your-deployment>/skills/SKILL.md — an installable skill with frontmatter.
mkdir -p ~/.claude/skills/markrelay-email
curl -fsS https://<your-deployment>/skills/SKILL.md \
  > ~/.claude/skills/markrelay-email/SKILL.md
export MARKRELAY_API_URL=https://<your-deployment>/openapi/v1
export MARKRELAY_API_KEY=sk-...

MARKRELAY_API_URL is the complete API endpoint, including/openapi/v1. The generated skill and llms.txtrepeat the exact value for their deployment so agents do not need to infer it.

What an agent can do

  • Discover mailboxes available to its API key.
  • Send email with Markdown and personalization variables.
  • Triage inboxes by folder, unread state, sender, subject, and date.
  • Read and organize messages without relying on browser automation.
  • Reply and forward while preserving conversation context.
  • Upload and download files through reusable upload IDs, or link larger uploaded files by URL.

Example workflow

  1. Call GET /mailboxes and choose the configured address.
  2. List unread Inbox messages.
  3. Fetch full detail for the next conversation.
  4. Classify it, draft a reply, or send it to a human review queue.
  5. Reply and then update the message state.

Monitor a mailbox safely

For periodic checks, use an external scheduler and query with an inclusive dateFrom checkpoint. Keep a short overlap window, follow every cursor page, and deduplicate by the opaque message ID before advancing the checkpoint. Do not use read=false as an incremental-sync cursor: another client may mark new mail as read first.

Recommended guardrails

  • Use a dedicated key and mailbox for each agent workflow.
  • Require human approval for sensitive or high-value replies.
  • Validate recipients and attachments before sending.
  • Never automatically retry an ambiguous send, reply, or forward; these operations are not idempotent.
  • Move mail to trash by default because the DELETE endpoint is permanent.
  • Treat received HTML and attachments as untrusted, and uploaded file URLs as public bearer capabilities.
  • Rotate keys and review mailbox access regularly.
  • Use webhooks when the agent should react to new mail immediately.

See the complete Email API guide.

← PreviousInbound webhooksNext →Deliverability