@assistantmail/assistantmail-mcp 1.2.0 → 1.2.1

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 +127 -135
  2. package/package.json +1 -1
  3. package/src/index.js +838 -838
package/README.md CHANGED
@@ -1,174 +1,166 @@
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)
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.
12
-
13
- ## Environment variables
9
+ ```bash
10
+ npx @assistantmail/assistantmail-mcp
11
+ ```
14
12
 
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
13
+ ### Claude Desktop
65
14
 
66
15
  ```json
67
16
  {
68
- "tool": "assistantmail_list_mailboxes",
69
- "input": {
70
- "apiKey": "amk_..."
71
- }
17
+ "mcpServers": {
18
+ "assistantmail": {
19
+ "command": "npx",
20
+ "args": ["-y", "@assistantmail/assistantmail-mcp"],
21
+ "env": {
22
+ "ASSISTANT_MAIL_API_KEY": "amk_..."
23
+ }
24
+ }
25
+ }
72
26
  }
73
27
  ```
74
28
 
29
+ ### Cursor / VS Code (`.cursor/mcp.json` or `.vscode/mcp.json`)
30
+
75
31
  ```json
76
32
  {
77
- "tool": "assistantmail_get_mailbox",
78
- "input": {
79
- "mailboxId": "<mailbox-uuid>",
80
- "apiKey": "amk_..."
81
- }
33
+ "servers": {
34
+ "assistantmail": {
35
+ "command": "npx",
36
+ "args": ["-y", "@assistantmail/assistantmail-mcp"],
37
+ "env": {
38
+ "ASSISTANT_MAIL_API_KEY": "amk_..."
39
+ }
40
+ }
41
+ }
82
42
  }
83
43
  ```
84
44
 
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
- }
45
+ ## Prerequisites
46
+
47
+ An AssistantMail account and API key are required before the server can do anything useful.
48
+
49
+ 1. Sign in at [app.assistant-mail.ai](https://app.assistant-mail.ai).
50
+ 2. Go to **API Keys** and create a new key. Copy it immediately — it is only shown once.
51
+ 3. Set `ASSISTANT_MAIL_API_KEY` in the MCP server environment (see configs above), or pass `apiKey` directly in each tool call.
52
+
53
+ Mail API routes use a `mailboxId` (UUID), not an email address. Use `assistantmail_list_mailboxes` after connecting to discover your mailbox IDs.
54
+
55
+ ## Environment variables
56
+
57
+ | Variable | Default | Description |
58
+ |---|---|---|
59
+ | `ASSISTANT_MAIL_API_KEY` | _(none)_ | API key (`amk_...`). Can be omitted if passed per-tool. |
60
+ | `ASSISTANT_MAIL_API_BASE_URL` | `https://api.assistant-mail.ai` | The public API for the AssistantMail service |
61
+
62
+ ## Tools
63
+
64
+ ### Diagnostics
65
+ | Tool | Description |
66
+ |---|---|
67
+ | `assistantmail_health` | Check that the MCP server is running and confirm the API base URL. No API key required. |
68
+
69
+ ### Account
70
+ | Tool | Description |
71
+ |---|---|
72
+ | `assistantmail_get_me` | Get account profile and plan tier. |
73
+ | `assistantmail_get_inbound_policy` | Get the current inbound email policy (who can send to this account's mailboxes). |
74
+ | `assistantmail_update_inbound_policy` | Update the inbound policy (if allowed by selected account tier). Accepted values: `owner`, `list`, `sent`. Use `allowedSenders` with `list`. |
75
+
76
+ ### Mailboxes
77
+ | Tool | Description |
78
+ |---|---|
79
+ | `assistantmail_list_mailboxes` | List all mailboxes on the account. Returns `mailboxId` needed for message operations. |
80
+ | `assistantmail_create_mailbox` | Create a new mailbox (if allowed by selected account tier), optionally specifying `displayName` and `address`. |
81
+ | `assistantmail_get_mailbox` | Get metadata for a single mailbox by `mailboxId`. |
82
+ | `assistantmail_update_mailbox` | Update a mailbox's display name. |
83
+ | `assistantmail_delete_mailbox` | Permanently delete a mailbox and all its messages. THIS ACTION HAS NO CONFIRMATION. USE CAREFULLY. |
84
+
85
+ ### Messages
86
+ | Tool | Description |
87
+ |---|---|
88
+ | `assistantmail_list_messages` | List inbound and outbound messages for a mailbox. Supports `since` (ISO timestamp) and `limit` (max 100). |
89
+ | `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. |
90
+ | `assistantmail_send_email` | Queue an outbound email. Requires `to`, `subject`, and at least one of `text` or `html`. |
91
+ | `assistantmail_delete_messages` | Delete messages by `messageIds` array, or pass `deleteAll: true` to clear the mailbox. |
92
+ | `assistantmail_get_usage` | Get daily and monthly send quota usage for a mailbox. A `null` limit means unlimited. |
93
+
94
+ ### Recipients
95
+ | Tool | Description |
96
+ |---|---|
97
+ | `assistantmail_list_recipients` | List approved and pending recipients for the account. |
98
+ | `assistantmail_add_recipient` | Add a recipient. Sends a consent invitation email when required by the account's plan. |
99
+ | `assistantmail_remove_recipient` | Remove a recipient from the allowed list. |
100
+
101
+ ### Reference tools
102
+ 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.
103
+
104
+ | Tool | Description |
105
+ |---|---|
106
+ | `assistantmail_send_email_reference` | Endpoint, headers, and body fields for `POST /v1/mailboxes/{mailboxId}/messages`. |
107
+ | `assistantmail_list_messages_reference` | Endpoint and query params for `GET /v1/mailboxes/{mailboxId}/messages`. |
108
+ | `assistantmail_get_message_reference` | Endpoint and response schema for `GET /v1/mailboxes/{mailboxId}/messages/{messageId}`. |
109
+ | `assistantmail_get_usage_reference` | Endpoint and response schema for `GET /v1/mailboxes/{mailboxId}/usage`. |
110
+
111
+ ## Quick start
112
+
113
+ ```bash
114
+ API_KEY="amk_..."
115
+ BASE="https://api.assistant-mail.ai"
116
+
117
+ # 1) Discover your mailboxId
118
+ curl "$BASE/v1/mailboxes" -H "x-api-key: $API_KEY"
119
+
120
+ # 2) Send an email
121
+ curl -X POST "$BASE/v1/mailboxes/<mailboxId>/messages" \
122
+ -H "x-api-key: $API_KEY" \
123
+ -H "Content-Type: application/json" \
124
+ -d '{"to":"recipient@example.com","subject":"Hello","text":"Hi there"}'
125
+
126
+ # 3) Read inbox
127
+ curl "$BASE/v1/mailboxes/<mailboxId>/messages" -H "x-api-key: $API_KEY"
95
128
  ```
96
129
 
130
+ ## Tool call examples
131
+
97
132
  ```json
98
- {
99
- "tool": "assistantmail_get_message",
100
- "input": {
101
- "mailboxId": "<mailbox-uuid>",
102
- "messageId": "<message-uuid>",
103
- "apiKey": "amk_..."
104
- }
105
- }
133
+ { "tool": "assistantmail_list_mailboxes", "input": { "apiKey": "amk_..." } }
106
134
  ```
107
135
 
108
136
  ```json
109
137
  {
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
- }
138
+ "tool": "assistantmail_list_messages",
139
+ "input": { "mailboxId": "<uuid>", "limit": 20, "since": "2026-01-01T00:00:00.000Z" }
118
140
  }
119
141
  ```
120
142
 
121
143
  ```json
122
144
  {
123
- "tool": "assistantmail_get_usage",
124
- "input": {
125
- "mailboxId": "<mailbox-uuid>",
126
- "apiKey": "amk_..."
127
- }
145
+ "tool": "assistantmail_get_message",
146
+ "input": { "mailboxId": "<uuid>", "messageId": "<uuid>" }
128
147
  }
129
148
  ```
130
149
 
131
150
  ```json
132
151
  {
133
- "tool": "assistantmail_list_recipients",
134
- "input": {
135
- "apiKey": "amk_..."
136
- }
152
+ "tool": "assistantmail_send_email",
153
+ "input": {
154
+ "mailboxId": "<uuid>",
155
+ "to": "recipient@example.com",
156
+ "subject": "Hello",
157
+ "text": "Hi there"
158
+ }
137
159
  }
138
160
  ```
139
161
 
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
151
-
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
- ```
162
+ If `ASSISTANT_MAIL_API_KEY` is set in the server environment, `apiKey` can be omitted from all tool inputs.
169
163
 
170
- ## Publish
164
+ ---
171
165
 
172
- ```bash
173
- npm publish --access public
174
- ```
166
+ [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,6 +1,6 @@
1
1
  {
2
2
  "name": "@assistantmail/assistantmail-mcp",
3
- "version": "1.2.0",
3
+ "version": "1.2.1",
4
4
  "description": "AssistantMail MCP server",
5
5
  "type": "module",
6
6
  "bin": {