Email Module — MCP Tool Specification

This document describes the 12 MCP tools exposed by codomyrmex.email.mcp_tools. AgentMail tools require AGENTMAIL_API_KEY. Gmail tools require GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_REFRESH_TOKEN.

---

agentmail_send_message

Send an email immediately via AgentMail.

Input Schema

Parameter	Type	Required	Description
to	List[str]	Yes	Recipient email addresses
subject	str	Yes	Email subject line
text	str	Yes	Plain-text message body
html	`str \	None`	No HTML message body
cc	`List[str] \	None`	No CC recipients
bcc	`List[str] \	None`	No BCC recipients
inbox_id	`str \	None`	No Sending inbox (defaults to AGENTMAIL_DEFAULT_INBOX)

Output Schema

{
  "status": "ok",
  "message_id": "msg_...",
  "thread_id": "thr_...",
  "subject": "...",
  "to": ["recipient@example.com"]
}

---

agentmail_list_messages

List recent messages in an AgentMail inbox.

Input Schema

Parameter	Type	Required	Description
inbox_id	`str \	None`	No Inbox to query
limit	int	No	Max results (default 20)
labels	`List[str] \	None`	No Filter by labels

Output Schema

{
  "status": "ok",
  "count": 5,
  "messages": [
    {
      "message_id": "msg_...",
      "thread_id": "thr_...",
      "subject": "...",
      "from": "sender@example.com",
      "date": "2026-02-23T10:00:00",
      "labels": [],
      "preview": "First 200 chars of body..."
    }
  ]
}

---

agentmail_get_message

Fetch full content of a specific message.

Input Schema

Parameter	Type	Required	Description
message_id	str	Yes	AgentMail message ID
inbox_id	`str \	None`	No Containing inbox

Output Schema

{
  "status": "ok",
  "message": {
    "message_id": "msg_...",
    "thread_id": "thr_...",
    "subject": "...",
    "from": "sender@example.com",
    "from_name": "Sender Name",
    "to": ["recipient@example.com"],
    "cc": [],
    "date": "2026-02-23T10:00:00",
    "body_text": "...",
    "body_html": null,
    "labels": []
  }
}

---

agentmail_reply_to_message

Reply to an existing message.

Input Schema

Parameter	Type	Required	Description
message_id	str	Yes	Message to reply to
text	str	Yes	Plain-text reply body
html	`str \	None`	No HTML reply body
reply_all	bool	No	Reply to all recipients (default false)
inbox_id	`str \	None`	No Sending inbox

Output Schema

{
  "status": "ok",
  "message_id": "msg_...",
  "thread_id": "thr_...",
  "subject": "Re: ..."
}

---

agentmail_list_inboxes

List all inboxes for the account.

Input Schema

Parameter	Type	Required	Description
limit	int	No	Max inboxes to return (default 50)

Output Schema

{
  "status": "ok",
  "count": 3,
  "inboxes": [
    {
      "inbox_id": "username@agentmail.to",
      "display_name": "My Inbox",
      "pod_id": null,
      "created_at": "2026-01-01T00:00:00"
    }
  ]
}

---

agentmail_create_inbox

Create a new inbox.

Input Schema

Parameter	Type	Required	Description
username	`str \	None`	No Username (auto-generated if omitted)
display_name	`str \	None`	No Human-readable label

Output Schema

{
  "status": "ok",
  "inbox_id": "username@agentmail.to",
  "display_name": "My New Inbox",
  "pod_id": null,
  "created_at": "2026-02-23T10:00:00"
}

---

agentmail_list_threads

List conversation threads in an inbox.

Input Schema

Parameter	Type	Required	Description
inbox_id	`str \	None`	No Inbox to query
limit	int	No	Max threads (default 20)
labels	`List[str] \	None`	No Filter by labels

Output Schema

{
  "status": "ok",
  "count": 4,
  "threads": [
    {
      "thread_id": "thr_...",
      "inbox_id": "username@agentmail.to",
      "subject": "...",
      "message_count": 3,
      "labels": [],
      "created_at": "2026-02-23T09:00:00"
    }
  ]
}

---

agentmail_create_webhook

Register a webhook for AgentMail events.

Input Schema

Parameter	Type	Required	Description
url	str	Yes	HTTPS endpoint to receive events
event_types	List[str]	Yes	Events to subscribe to (e.g. ["message.received"])
inbox_ids	`List[str] \	None`	No Scope to specific inboxes

Common Event Types

• message.received — incoming message arrived
• message.sent — outgoing message delivered
• message.delivered — delivery confirmed
• message.bounced — delivery failed

Output Schema

{
  "status": "ok",
  "webhook_id": "whk_...",
  "url": "https://example.com/webhook",
  "event_types": ["message.received"],
  "inbox_ids": []
}

---

gmail_send_message

Send an email via Gmail API using OAuth2 credentials.

Input Schema

Parameter	Type	Required	Description
to	List[str]	Yes	Recipient email addresses
subject	str	Yes	Email subject line
body_text	str	Yes	Plain-text message body
body_html	`str \	None`	No HTML message body
cc	`List[str] \	None`	No CC recipients
bcc	`List[str] \	None`	No BCC recipients

Output Schema

{
  "status": "ok",
  "message_id": "msg_...",
  "thread_id": "thr_...",
  "subject": "...",
  "to": ["recipient@example.com"]
}

---

gmail_list_messages

List messages in the Gmail inbox with optional search query.

Input Schema

Parameter	Type	Required	Description
query	str	No	Gmail search query (e.g. "is:unread", "from:user@example.com"). Default: empty (all messages)
max_results	int	No	Maximum messages to return (default 20)

Output Schema

{
  "status": "ok",
  "count": 5,
  "messages": [
    {
      "message_id": "msg_...",
      "thread_id": "thr_...",
      "subject": "...",
      "from": "sender@example.com",
      "date": "2026-02-23T10:00:00",
      "labels": [],
      "preview": "First 200 chars of body..."
    }
  ]
}

---

gmail_get_message

Fetch a specific Gmail message by its ID.

Input Schema

Parameter	Type	Required	Description
message_id	str	Yes	The Gmail message ID (opaque string from the Gmail API)

Output Schema

{
  "status": "ok",
  "message": {
    "message_id": "msg_...",
    "thread_id": "thr_...",
    "subject": "...",
    "from": "sender@example.com",
    "from_name": "Sender Name",
    "to": ["recipient@example.com"],
    "cc": [],
    "date": "2026-02-23T10:00:00",
    "body_text": "...",
    "body_html": null,
    "labels": []
  }
}

---

gmail_create_draft

Create a Gmail draft without sending it.

Input Schema

Parameter	Type	Required	Description
to	List[str]	Yes	Recipient email addresses
subject	str	Yes	Email subject line
body_text	str	Yes	Plain-text message body
body_html	`str \	None`	No HTML message body
cc	`List[str] \	None`	No CC recipients
bcc	`List[str] \	None`	No BCC recipients

Output Schema

{
  "status": "ok",
  "draft_id": "draft_..."
}

---

Error Response (all tools)

{
  "status": "error",
  "error": "Descriptive error message"
}