@assistantmail/assistantmail-mcp 1.2.0 → 1.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +141 -134
  2. package/package.json +12 -3
  3. package/src/index.js +838 -838
package/README.md CHANGED
@@ -1,174 +1,181 @@
1
1
  # assistantmail-mcp
2
2
 
3
- AssistantMail MCP server package for npm.
3
+ MCP server for [AssistantMail](https://assistant-mail.ai) — lets AI agents send and receive email through a managed mailbox.
4
4
 
5
- ## What this MCP server provides
5
+ [Website](https://assistant-mail.ai) · [Privacy Policy](https://assistant-mail.ai/privacy.html) · [Terms of Use](https://assistant-mail.ai/terms.html) · [Contributing](./CONTRIBUTING.md)
6
6
 
7
- This package exposes both:
8
- - direct tools that call AssistantMail for mailbox/message operations
9
- - reference tools that describe raw REST endpoint details
7
+ ## Installation
10
8
 
11
- It does not mint credentials automatically; you must provision an API key first.
9
+ ```bash
10
+ npx @assistantmail/assistantmail-mcp
11
+ ```
12
12
 
13
- ## Environment variables
13
+ Requires Node.js 24 or newer.
14
+
15
+ ## For npm users
16
+
17
+ If you are installing from npm and want the shortest setup path:
14
18
 
15
- - `ASSISTANT_MAIL_API_BASE_URL` (optional, defaults to `https://api.assistant-mail.ai`)
16
- - `ASSISTANT_MAIL_API_KEY` (optional, must start with `amk_`; used by direct tools when `apiKey` input is omitted)
17
-
18
- ## Available tools
19
-
20
- - `assistantmail_health`
21
- - `assistantmail_get_me` (direct API call)
22
- - `assistantmail_get_inbound_policy` (direct API call)
23
- - `assistantmail_update_inbound_policy` (direct API call)
24
- - `assistantmail_list_mailboxes` (direct API call)
25
- - `assistantmail_create_mailbox` (direct API call)
26
- - `assistantmail_get_mailbox` (direct API call)
27
- - `assistantmail_update_mailbox` (direct API call)
28
- - `assistantmail_delete_mailbox` (direct API call)
29
- - `assistantmail_list_messages` (direct API call)
30
- - `assistantmail_get_message` (direct API call)
31
- - `assistantmail_send_email` (direct API call)
32
- - `assistantmail_delete_messages` (direct API call)
33
- - `assistantmail_get_usage` (direct API call)
34
- - `assistantmail_list_recipients` (direct API call)
35
- - `assistantmail_add_recipient` (direct API call)
36
- - `assistantmail_remove_recipient` (direct API call)
37
- - `assistantmail_send_email_reference`
38
- - `assistantmail_list_messages_reference`
39
- - `assistantmail_get_message_reference`
40
- - `assistantmail_get_usage_reference`
41
-
42
- These direct tools cover the API-key operational endpoints agents are expected to call.
43
-
44
- ## Required prerequisites
45
-
46
- - Knowing a mailbox address (for example, `agent-b1e4643c@assistant-mail.ai`) is not enough to access messages or send mail.
47
- - Mail routes use `mailboxId` (UUID), not email address, in path parameters.
48
- - A valid auth credential is required for mailbox routes:
49
- - Cognito JWT, or
50
- - AssistantMail API key (`amk_...`)
51
-
52
- ## How an agent gets an API key
53
-
54
- 1. Human owner signs in with Cognito.
55
- 2. Human owner creates key via `POST /v1/api-keys`.
56
- 3. Human owner securely shares returned key with the agent runtime.
57
- 4. Agent calls `GET /v1/mailboxes` with that key to obtain the mailbox's `mailboxId`.
58
- 5. Agent uses `mailboxId` for send/list/get/usage endpoints.
59
-
60
- Important:
61
- - API keys are shown once at creation.
62
- - API key management (`GET/POST/DELETE /v1/api-keys`) requires Cognito session.
63
-
64
- ## Direct MCP tool examples
19
+ 1. Install/run with:
20
+
21
+ ```bash
22
+ npx -y @assistantmail/assistantmail-mcp
23
+ ```
24
+
25
+ 2. Set `ASSISTANT_MAIL_API_KEY` in your MCP client environment.
26
+ 3. Call `assistantmail_list_mailboxes` first to get your `mailboxId`.
27
+
28
+ ### Claude Desktop
65
29
 
66
30
  ```json
67
31
  {
68
- "tool": "assistantmail_list_mailboxes",
69
- "input": {
70
- "apiKey": "amk_..."
71
- }
32
+ "mcpServers": {
33
+ "assistantmail": {
34
+ "command": "npx",
35
+ "args": ["-y", "@assistantmail/assistantmail-mcp"],
36
+ "env": {
37
+ "ASSISTANT_MAIL_API_KEY": "amk_..."
38
+ }
39
+ }
40
+ }
72
41
  }
73
42
  ```
74
43
 
44
+ ### Cursor / VS Code (`.cursor/mcp.json` or `.vscode/mcp.json`)
45
+
75
46
  ```json
76
47
  {
77
- "tool": "assistantmail_get_mailbox",
78
- "input": {
79
- "mailboxId": "<mailbox-uuid>",
80
- "apiKey": "amk_..."
81
- }
48
+ "servers": {
49
+ "assistantmail": {
50
+ "command": "npx",
51
+ "args": ["-y", "@assistantmail/assistantmail-mcp"],
52
+ "env": {
53
+ "ASSISTANT_MAIL_API_KEY": "amk_..."
54
+ }
55
+ }
56
+ }
82
57
  }
83
58
  ```
84
59
 
85
- ```json
86
- {
87
- "tool": "assistantmail_list_messages",
88
- "input": {
89
- "mailboxId": "<mailbox-uuid>",
90
- "limit": 50,
91
- "since": "2026-01-01T00:00:00.000Z",
92
- "apiKey": "amk_..."
93
- }
94
- }
60
+ ## Prerequisites
61
+
62
+ An AssistantMail account and API key are required before the server can do anything useful.
63
+
64
+ 1. Sign in at [app.assistant-mail.ai](https://app.assistant-mail.ai).
65
+ 2. Go to **API Keys** and create a new key. Copy it immediately — it is only shown once.
66
+ 3. Set `ASSISTANT_MAIL_API_KEY` in the MCP server environment (see configs above), or pass `apiKey` directly in each tool call.
67
+
68
+ Mail API routes use a `mailboxId` (UUID), not an email address. Use `assistantmail_list_mailboxes` after connecting to discover your mailbox IDs.
69
+
70
+ ## Environment variables
71
+
72
+ | Variable | Default | Description |
73
+ |---|---|---|
74
+ | `ASSISTANT_MAIL_API_KEY` | _(none)_ | API key (`amk_...`). Can be omitted if passed per-tool. |
75
+ | `ASSISTANT_MAIL_API_BASE_URL` | `https://api.assistant-mail.ai` | The public API for the AssistantMail service |
76
+
77
+ ## Tools
78
+
79
+ ### Diagnostics
80
+ | Tool | Description |
81
+ |---|---|
82
+ | `assistantmail_health` | Check that the MCP server is running and confirm the API base URL. No API key required. |
83
+
84
+ ### Account
85
+ | Tool | Description |
86
+ |---|---|
87
+ | `assistantmail_get_me` | Get account profile and plan tier. |
88
+ | `assistantmail_get_inbound_policy` | Get the current inbound email policy (who can send to this account's mailboxes). |
89
+ | `assistantmail_update_inbound_policy` | Update the inbound policy (if allowed by selected account tier). Accepted values: `owner`, `list`, `sent`. Use `allowedSenders` with `list`. |
90
+
91
+ ### Mailboxes
92
+ | Tool | Description |
93
+ |---|---|
94
+ | `assistantmail_list_mailboxes` | List all mailboxes on the account. Returns `mailboxId` needed for message operations. |
95
+ | `assistantmail_create_mailbox` | Create a new mailbox (if allowed by selected account tier), optionally specifying `displayName` and `address`. |
96
+ | `assistantmail_get_mailbox` | Get metadata for a single mailbox by `mailboxId`. |
97
+ | `assistantmail_update_mailbox` | Update a mailbox's display name. |
98
+ | `assistantmail_delete_mailbox` | Permanently delete a mailbox and all its messages. THIS ACTION HAS NO CONFIRMATION. USE CAREFULLY. |
99
+
100
+ ### Messages
101
+ | Tool | Description |
102
+ |---|---|
103
+ | `assistantmail_list_messages` | List inbound and outbound messages for a mailbox. Supports `since` (ISO timestamp) and `limit` (max 100). |
104
+ | `assistantmail_get_message` | Fetch a single message including `textBody` and `htmlBody`. Bodies are only returned within the plan's retention window; `bodyExpired: true` is set if the window has elapsed. |
105
+ | `assistantmail_send_email` | Queue an outbound email. Requires `to`, `subject`, and at least one of `text` or `html`. |
106
+ | `assistantmail_delete_messages` | Delete messages by `messageIds` array, or pass `deleteAll: true` to clear the mailbox. |
107
+ | `assistantmail_get_usage` | Get daily and monthly send quota usage for a mailbox. A `null` limit means unlimited. |
108
+
109
+ ### Recipients
110
+ | Tool | Description |
111
+ |---|---|
112
+ | `assistantmail_list_recipients` | List approved and pending recipients for the account. |
113
+ | `assistantmail_add_recipient` | Add a recipient. Sends a consent invitation email when required by the account's plan. |
114
+ | `assistantmail_remove_recipient` | Remove a recipient from the allowed list. |
115
+
116
+ ### Reference tools
117
+ These return raw REST endpoint details rather than calling the API. Use them when you need to construct a request manually or inspect the exact URL and response schema.
118
+
119
+ | Tool | Description |
120
+ |---|---|
121
+ | `assistantmail_send_email_reference` | Endpoint, headers, and body fields for `POST /v1/mailboxes/{mailboxId}/messages`. |
122
+ | `assistantmail_list_messages_reference` | Endpoint and query params for `GET /v1/mailboxes/{mailboxId}/messages`. |
123
+ | `assistantmail_get_message_reference` | Endpoint and response schema for `GET /v1/mailboxes/{mailboxId}/messages/{messageId}`. |
124
+ | `assistantmail_get_usage_reference` | Endpoint and response schema for `GET /v1/mailboxes/{mailboxId}/usage`. |
125
+
126
+ ## Quick start
127
+
128
+ ```bash
129
+ API_KEY="amk_..."
130
+ BASE="https://api.assistant-mail.ai"
131
+
132
+ # 1) Discover your mailboxId
133
+ curl "$BASE/v1/mailboxes" -H "x-api-key: $API_KEY"
134
+
135
+ # 2) Send an email
136
+ curl -X POST "$BASE/v1/mailboxes/<mailboxId>/messages" \
137
+ -H "x-api-key: $API_KEY" \
138
+ -H "Content-Type: application/json" \
139
+ -d '{"to":"recipient@example.com","subject":"Hello","text":"Hi there"}'
140
+
141
+ # 3) Read inbox
142
+ curl "$BASE/v1/mailboxes/<mailboxId>/messages" -H "x-api-key: $API_KEY"
95
143
  ```
96
144
 
145
+ ## Tool call examples
146
+
97
147
  ```json
98
- {
99
- "tool": "assistantmail_get_message",
100
- "input": {
101
- "mailboxId": "<mailbox-uuid>",
102
- "messageId": "<message-uuid>",
103
- "apiKey": "amk_..."
104
- }
105
- }
148
+ { "tool": "assistantmail_list_mailboxes", "input": { "apiKey": "amk_..." } }
106
149
  ```
107
150
 
108
151
  ```json
109
152
  {
110
- "tool": "assistantmail_send_email",
111
- "input": {
112
- "mailboxId": "<mailbox-uuid>",
113
- "to": "recipient@example.com",
114
- "subject": "Hello",
115
- "text": "Hi there",
116
- "apiKey": "amk_..."
117
- }
153
+ "tool": "assistantmail_list_messages",
154
+ "input": { "mailboxId": "<uuid>", "limit": 20, "since": "2026-01-01T00:00:00.000Z" }
118
155
  }
119
156
  ```
120
157
 
121
158
  ```json
122
159
  {
123
- "tool": "assistantmail_get_usage",
124
- "input": {
125
- "mailboxId": "<mailbox-uuid>",
126
- "apiKey": "amk_..."
127
- }
160
+ "tool": "assistantmail_get_message",
161
+ "input": { "mailboxId": "<uuid>", "messageId": "<uuid>" }
128
162
  }
129
163
  ```
130
164
 
131
165
  ```json
132
166
  {
133
- "tool": "assistantmail_list_recipients",
134
- "input": {
135
- "apiKey": "amk_..."
136
- }
167
+ "tool": "assistantmail_send_email",
168
+ "input": {
169
+ "mailboxId": "<uuid>",
170
+ "to": "recipient@example.com",
171
+ "subject": "Hello",
172
+ "text": "Hi there"
173
+ }
137
174
  }
138
175
  ```
139
176
 
140
- If `ASSISTANT_MAIL_API_KEY` is set in the server environment, `apiKey` can be omitted from tool inputs.
141
-
142
- ## Run locally
143
-
144
- ```bash
145
- npm install
146
- npm run build
147
- npm start
148
- ```
149
-
150
- ## Minimal bootstrap example
177
+ If `ASSISTANT_MAIL_API_KEY` is set in the server environment, `apiKey` can be omitted from all tool inputs.
151
178
 
152
- ```bash
153
- # 1) Create API key (Cognito token required)
154
- curl -X POST "$ASSISTANT_MAIL_API_BASE_URL/v1/api-keys" \
155
- -H "Authorization: Bearer <cognito-jwt>" \
156
- -H "Content-Type: application/json" \
157
- -d '{"name":"My Agent Key"}'
158
-
159
- # 2) List mailboxes to get mailboxId
160
- curl "$ASSISTANT_MAIL_API_BASE_URL/v1/mailboxes" \
161
- -H "x-api-key: <amk_key>"
162
-
163
- # 3) Send using mailboxId
164
- curl -X POST "$ASSISTANT_MAIL_API_BASE_URL/v1/mailboxes/<mailboxId>/messages" \
165
- -H "x-api-key: <amk_key>" \
166
- -H "Content-Type: application/json" \
167
- -d '{"to":"recipient@example.com","subject":"Hello","text":"Hi there"}'
168
- ```
169
-
170
- ## Publish
179
+ ---
171
180
 
172
- ```bash
173
- npm publish --access public
174
- ```
181
+ [AssistantMail](https://assistant-mail.ai) · [Privacy Policy](https://assistant-mail.ai/privacy.html) · [Terms of Use](https://assistant-mail.ai/terms.html)
package/package.json CHANGED
@@ -1,7 +1,15 @@
1
1
  {
2
2
  "name": "@assistantmail/assistantmail-mcp",
3
- "version": "1.2.0",
3
+ "version": "1.2.2",
4
4
  "description": "AssistantMail MCP server",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "https://github.com/AssistantMail/assistantmail-mcp.git"
8
+ },
9
+ "homepage": "https://assistant-mail.ai",
10
+ "bug": {
11
+ "url": "https://github.com/AssistantMail/assistantmail-mcp/issues"
12
+ },
5
13
  "type": "module",
6
14
  "bin": {
7
15
  "assistantmail-mcp": "src/index.js"
@@ -13,6 +21,7 @@
13
21
  ],
14
22
  "scripts": {
15
23
  "build": "node --check src/index.js",
24
+ "lint": "node --check src/index.js",
16
25
  "start": "node src/index.js"
17
26
  },
18
27
  "keywords": [
@@ -22,13 +31,13 @@
22
31
  "openai",
23
32
  "OpenClaw"
24
33
  ],
25
- "author": "Crider Technologies",
34
+ "author": "AssistantMail",
26
35
  "license": "MIT",
27
36
  "publishConfig": {
28
37
  "access": "public"
29
38
  },
30
39
  "engines": {
31
- "node": ">=20"
40
+ "node": ">=24"
32
41
  },
33
42
  "dependencies": {
34
43
  "@modelcontextprotocol/sdk": "^1.29.0",