email

Create email account

createEmailAddress

Create an email account with no signup and get its api_key; call this first when you have no Primitive API key and the user wants to send or receive email. Pass api_key as the api_key argument on every later Primitive call, exactly as returned. address is a domain, not a mailbox; sender_address (such as agent@pink-ram.primitive.email) is the mailbox sendEmail sends from. can_send_to lists the only recipients the account may email. If this host already has an inbox, it comes back with existing_account: true: report it as their existing inbox. Without an api_key the user must sign in. Creating the account accepts Primitive's terms of service for the user: tell them. Result: org_id, address (null without a managed inbox), existing_account and message; sender_address when address is set; api_key and can_send_to unless the key cannot be returned; for a new account, plan, limits and upgrade.

Input Schema

Name	Required	Description	Default
`device_name`	No	Name of the app creating the account, such as ChatGPT. The user sees it later and recognises where the account came from.
`terms_accepted`	Yes	Confirms the user agrees to Primitive's terms of service (primitive.dev/terms).

Output Schema

Name	Required	Description
`plan`	No	New account only: plan name.
`limits`	No	New account only: what the plan allows.
`org_id`	Yes	Account id.
`address`	Yes	Managed inbox domain, not a mailbox: send from sender_address. Null when the account has none.
`api_key`	No	Pass as api_key on later calls. Absent when it cannot be returned.
`message`	Yes	What to tell the user about this account.
`upgrade`	No	New account only: how to move to a full account.
`can_send_to`	No	Who this account may email. Absent when no api_key is available.
`sender_address`	No	Mailbox to send from. Set when address is.
`existing_account`	Yes	True when this host already had an inbox and it was returned again.

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedNov 3, 2026

changedOutput schema / properties / can_send_to / properties / rules / items / properties / type / description

Previous value: -"any_recipient, primitive_managed_domain, managed_zone, your_domain, address, org_member_email or opted_in_domains."New value: +"any_recipient, primitive_managed_domain, managed_zone, your_domain, address, org_member_email, org_member_emails or opted_in_domains."

removedOutput schema / properties / funding

Removed value: -{
-  "additionalProperties": false,
-  "description": "New account only: how to fund credits.",
-  "properties": {
-    "description": {
-      "description": "What funding does.",
-      "type": "string"
-    },
-    "url": {
-      "description": "Where to fund it; null if not available.",
-      "type": [
-        "string",
-        "null"
-      ]
-    }
-  },
-  "required": [
-    "url",
-    "description"
-  ],
-  "type": "object"
-}

changedOutput schema / properties / message / description

Previous value: -"Existing inbox only: what to tell the user."New value: +"What to tell the user about this account."

changedOutput schema / properties / plan / description

Previous value: -"New account only: plan name, agent."New value: +"New account only: plan name."

addedOutput schema / properties / plan / enum
```
Added value: +[
+  "agent"
+]
```
addedOutput schema / properties / upgrade / properties / plan / enum
```
Added value: +[
+  "developer"
+]
```

changedOutput schema / required

Previous value: -[
-  "org_id",
-  "address",
-  "existing_account"
-]New value: +[
+  "org_id",
+  "address",
+  "existing_account",
+  "message"
+]

Changed7 schema fields changedNov 2, 2026

changedOutput schema / properties / can_send_to / properties / rules / items / properties / type / description

Previous value: -"any_recipient, primitive_managed_domain, managed_zone, your_domain, address, org_member_email, org_member_emails or opted_in_domains."New value: +"any_recipient, primitive_managed_domain, managed_zone, your_domain, address, org_member_email or opted_in_domains."

addedOutput schema / properties / funding

Added value: +{
+  "additionalProperties": false,
+  "description": "New account only: how to fund credits.",
+  "properties": {
+    "description": {
+      "description": "What funding does.",
+      "type": "string"
+    },
+    "url": {
+      "description": "Where to fund it; null if not available.",
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "url",
+    "description"
+  ],
+  "type": "object"
+}

changedOutput schema / properties / message / description

Previous value: -"What to tell the user about this account."New value: +"Existing inbox only: what to tell the user."

changedOutput schema / properties / plan / description

Previous value: -"New account only: plan name."New value: +"New account only: plan name, agent."

removedOutput schema / properties / plan / enum
```
Removed value: -[
-  "agent"
-]
```
removedOutput schema / properties / upgrade / properties / plan / enum
```
Removed value: -[
-  "developer"
-]
```

changedOutput schema / required

Previous value: -[
-  "org_id",
-  "address",
-  "existing_account",
-  "message"
-]New value: +[
+  "org_id",
+  "address",
+  "existing_account"
+]

Changed7 schema fields changedNov 2, 2026

changedOutput schema / properties / can_send_to / properties / rules / items / properties / type / description

Previous value: -"any_recipient, primitive_managed_domain, managed_zone, your_domain, address, org_member_email or opted_in_domains."New value: +"any_recipient, primitive_managed_domain, managed_zone, your_domain, address, org_member_email, org_member_emails or opted_in_domains."

removedOutput schema / properties / funding

Removed value: -{
-  "additionalProperties": false,
-  "description": "New account only: how to fund credits.",
-  "properties": {
-    "description": {
-      "description": "What funding does.",
-      "type": "string"
-    },
-    "url": {
-      "description": "Where to fund it; null if not available.",
-      "type": [
-        "string",
-        "null"
-      ]
-    }
-  },
-  "required": [
-    "url",
-    "description"
-  ],
-  "type": "object"
-}

changedOutput schema / properties / message / description

Previous value: -"Existing inbox only: what to tell the user."New value: +"What to tell the user about this account."

changedOutput schema / properties / plan / description

Previous value: -"New account only: plan name, agent."New value: +"New account only: plan name."

addedOutput schema / properties / plan / enum
```
Added value: +[
+  "agent"
+]
```
addedOutput schema / properties / upgrade / properties / plan / enum
```
Added value: +[
+  "developer"
+]
```

changedOutput schema / required

Previous value: -[
-  "org_id",
-  "address",
-  "existing_account"
-]New value: +[
+  "org_id",
+  "address",
+  "existing_account",
+  "message"
+]

Changed1 schema field changedOct 23, 2026

changedOutput schema / properties / address / description

Previous value: -"Managed inbox domain, not a mailbox: send from sender_address."New value: +"Managed inbox domain, not a mailbox: send from sender_address. Null when the account has none."

Changed17 schema fields changedOct 22, 2026

addedOutput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / description

Previous value: -"Envelope; the result is in data.data."New value: +"The managed inbox, its sender mailbox and its api_key."

addedOutput schema / properties / address

Added value: +{
+  "description": "Managed inbox domain, not a mailbox: send from sender_address.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / api_key

Added value: +{
+  "description": "Pass as api_key on later calls. Absent when it cannot be returned.",
+  "type": "string"
+}

addedOutput schema / properties / can_send_to

Added value: +{
+  "additionalProperties": false,
+  "description": "Who this account may email. Absent when no api_key is available.",
+  "properties": {
+    "address_rules_omitted": {
+      "description": "Address rules left out of rules; set when some were.",
+      "type": "integer"
+    },
+    "address_rules_partial": {
+      "description": "True when the address rules are a sample: an unlisted address may be allowed.",
+      "type": "boolean"
+    },
+    "any_recipient": {
+      "description": "True when any recipient is allowed. Set when known.",
+      "type": "boolean"
+    },
+    "known": {
+      "description": "False when the rules could not be read; then only summary is set.",
+      "type": "boolean"
+    },
+    "rules": {
+      "description": "Who you may email, one rule per kind of recipient. Set when known.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "address": {
+            "description": "address and org_member_email rules only: the address.",
+            "type": "string"
+          },
+          "description": {
+            "description": "Who the rule allows, in words.",
+            "type": "string"
+          },
+          "domain": {
+            "description": "your_domain rules only: the domain.",
+            "type": "string"
+          },
+          "last_received_at": {
+            "description": "address rules only: last mail from it.",
+            "type": "string"
+          },
+          "received_count": {
+            "description": "address rules only: emails received from it.",
+            "type": "integer"
+          },
+          "type": {
+            "description": "any_recipient, primitive_managed_domain, managed_zone, your_domain, address, org_member_email or opted_in_domains.",
+            "type": "string"
+          },
+          "zone": {
+            "description": "managed_zone rules only: the zone.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "type",
+          "description"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "summary": {
+      "description": "Who this account can reach, to tell the user.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "known",
+    "summary"
+  ],
+  "type": "object"
+}

removedOutput schema / properties / data

Removed value: -{
-  "description": "API response: the result in data, or error.",
-  "properties": {
-    "data": {
-      "description": "The managed inbox and its api_key.",
-      "properties": {
-        "address": {
-          "description": "Managed inbox domain.",
-          "type": [
-            "string",
-            "null"
-          ]
-        },
-        "api_key": {
-          "description": "Pass as api_key on later calls; absent if unavailable.",
-          "type": "string"
-        },
-        "can_send_to": {
-          "description": "Who you may email.",
-          "properties": {
-            "any_recipient": {
-              "description": "Any recipient is allowed.",
-              "type": "boolean"
-            },
-            "rules": {
-              "description": "Who is allowed: each has a type and a description.",
-              "type": "array"
-            },
-            "summary": {
-              "description": "What to tell the user.",
-              "type": "string"
-            }
-          },
-          "type": "object"
-        },
-        "existing_account": {
-          "description": "This host's existing inbox, returned again.",
-          "type": "boolean"
-        },
-        "funding": {
-          "description": "Link to fund credits.",
-          "properties": {
-            "description": {
-              "type": "string"
-            },
-            "url": {
-              "type": [
-                "string",
-                "null"
-              ]
-            }
-          },
-          "type": "object"
-        },
-        "limits": {
-          "description": "What the plan allows.",
-          "properties": {
-            "api_per_minute": {
-              "type": [
-                "number",
-                "string"
-              ]
-            },
-            "send_per_day": {
-              "type": [
-                "number",
-                "string"
-              ]
-            },
-            "send_per_hour": {
-              "type": [
-                "number",
-                "string"
-              ]
-            },
-            "storage_mb": {
-              "type": [
-                "number",
-                "string"
-              ]
-            }
-          },
-          "type": "object"
-        },
-        "message": {
-          "description": "For an existing inbox: what to tell the user.",
-          "type": "string"
-        },
-        "org_id": {
-          "description": "Account id.",
-          "type": "string"
-        },
-        "plan": {
-          "description": "Plan name: agent.",
-          "type": "string"
-        },
-        "sender_address": {
-          "description": "Mailbox to send from.",
-          "type": "string"
-        },
-        "upgrade": {
-          "description": "How to move to a full account.",
-          "properties": {
-            "claim_path": {
-              "type": "string"
-            },
-            "description": {
-              "type": "string"
-            },
-            "plan": {
-              "type": "string"
-            }
-          },
-          "type": "object"
-        }
-      },
-      "type": [
-        "object",
-        "null"
-      ]
-    },
-    "error": {
-      "description": "Why the call was refused; absent on success.",
-      "properties": {
-        "code": {
-          "description": "Error code to branch on.",
-          "type": "string"
-        },
-        "message": {
-          "description": "What went wrong, in words.",
-          "type": "string"
-        }
-      },
-      "type": [
-        "object",
-        "null"
-      ]
-    },
-    "success": {
-      "description": "True when data holds the result.",
-      "type": "boolean"
-    }
-  },
-  "type": "object"
-}

addedOutput schema / properties / existing_account

Added value: +{
+  "description": "True when this host already had an inbox and it was returned again.",
+  "type": "boolean"
+}

addedOutput schema / properties / funding

Added value: +{
+  "additionalProperties": false,
+  "description": "New account only: how to fund credits.",
+  "properties": {
+    "description": {
+      "description": "What funding does.",
+      "type": "string"
+    },
+    "url": {
+      "description": "Where to fund it; null if not available.",
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "url",
+    "description"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / limits

Added value: +{
+  "additionalProperties": false,
+  "description": "New account only: what the plan allows.",
+  "properties": {
+    "api_per_minute": {
+      "description": "API requests per minute.",
+      "type": "integer"
+    },
+    "send_per_day": {
+      "description": "Emails it may send per day.",
+      "type": "integer"
+    },
+    "send_per_hour": {
+      "description": "Emails it may send per hour.",
+      "type": "integer"
+    },
+    "storage_mb": {
+      "description": "Mail storage, in MB.",
+      "type": "number"
+    }
+  },
+  "required": [
+    "send_per_hour",
+    "send_per_day",
+    "api_per_minute",
+    "storage_mb"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / message

Added value: +{
+  "description": "Existing inbox only: what to tell the user.",
+  "type": "string"
+}

addedOutput schema / properties / org_id

Added value: +{
+  "description": "Account id.",
+  "type": "string"
+}

addedOutput schema / properties / plan

Added value: +{
+  "description": "New account only: plan name, agent.",
+  "type": "string"
+}

addedOutput schema / properties / sender_address

Added value: +{
+  "description": "Mailbox to send from. Set when address is.",
+  "type": "string"
+}

removedOutput schema / properties / status

Removed value: -{
-  "description": "HTTP status; 2xx on success.",
-  "type": "number"
-}

removedOutput schema / properties / tool

Removed value: -{
-  "description": "Tool that answered.",
-  "type": "string"
-}

addedOutput schema / properties / upgrade

Added value: +{
+  "additionalProperties": false,
+  "description": "New account only: how to move to a full account.",
+  "properties": {
+    "claim_path": {
+      "description": "API path that claims the account.",
+      "type": "string"
+    },
+    "description": {
+      "description": "What upgrading does.",
+      "type": "string"
+    },
+    "plan": {
+      "description": "Plan it moves to.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "plan",
+    "description",
+    "claim_path"
+  ],
+  "type": "object"
+}

changedOutput schema / required

Previous value: -[
-  "tool",
-  "status",
-  "data"
-]New value: +[
+  "org_id",
+  "address",
+  "existing_account"
+]

Changed20 schema fields changedOct 22, 2026

changedInput schema / properties / terms_accepted / description

Previous value: -"Acceptance of Primitive's terms of service (primitive.dev/terms) for the user, recorded on the new account."New value: +"Confirms the user agrees to Primitive's terms of service (primitive.dev/terms)."

changedOutput schema / description

Previous value: -"Envelope; see data."New value: +"Envelope; the result is in data.data."

changedOutput schema / properties / data / description

Previous value: -"New account in data; existing inbox fields here."New value: +"API response: the result in data, or error."

removedOutput schema / properties / data / properties / address

Removed value: -{
-  "description": "Managed inbox domain.",
-  "type": [
-    "string",
-    "null"
-  ]
-}

removedOutput schema / properties / data / properties / api_key

Removed value: -{
-  "description": "Null when it cannot be returned.",
-  "type": [
-    "string",
-    "null"
-  ]
-}

removedOutput schema / properties / data / properties / can_send_to

Removed value: -{
-  "description": "Who you may email.",
-  "properties": {
-    "any_recipient": {
-      "description": "Any recipient is allowed.",
-      "type": "boolean"
-    },
-    "rules": {
-      "description": "Who is allowed: each has a type and a description.",
-      "type": "array"
-    },
-    "summary": {
-      "description": "What to tell the user.",
-      "type": "string"
-    }
-  },
-  "type": "object"
-}

changedOutput schema / properties / data / properties / data / properties / api_key / description

Previous value: -"Pass as api_key on later calls."New value: +"Pass as api_key on later calls; absent if unavailable."

addedOutput schema / properties / data / properties / data / properties / existing_account

Added value: +{
+  "description": "This host's existing inbox, returned again.",
+  "type": "boolean"
+}

addedOutput schema / properties / data / properties / data / properties / message

Added value: +{
+  "description": "For an existing inbox: what to tell the user.",
+  "type": "string"
+}

changedOutput schema / properties / data / properties / error / description

Previous value: -"Refusal: code, message."New value: +"Why the call was refused; absent on success."

addedOutput schema / properties / data / properties / error / properties

Added value: +{
+  "code": {
+    "description": "Error code to branch on.",
+    "type": "string"
+  },
+  "message": {
+    "description": "What went wrong, in words.",
+    "type": "string"
+  }
+}

addedOutput schema / properties / data / properties / error / type
```
Added value: +[
+  "object",
+  "null"
+]
```

removedOutput schema / properties / data / properties / existing_account

Removed value: -{
-  "description": "Existing inbox, returned again.",
-  "type": "boolean"
-}

removedOutput schema / properties / data / properties / message

Removed value: -{
-  "description": "What to tell the user.",
-  "type": "string"
-}

removedOutput schema / properties / data / properties / org_id

Removed value: -{
-  "description": "Account id.",
-  "type": "string"
-}

removedOutput schema / properties / data / properties / sender_address

Removed value: -{
-  "description": "Mailbox to send from.",
-  "type": "string"
-}

changedOutput schema / properties / data / properties / success / description

Previous value: -"Accepted."New value: +"True when data holds the result."

changedOutput schema / properties / data / type

Previous value: -[
-  "object",
-  "string",
-  "null"
-]New value: +"object"

changedOutput schema / properties / status / description

Previous value: -"HTTP status."New value: +"HTTP status; 2xx on success."

addedOutput schema / properties / tool / description
```
Added value: +"Tool that answered."
```

Changed13 schema fields changedOct 22, 2026

changedInput schema / properties / terms_accepted / description

Previous value: -"Confirms the user agrees to Primitive's terms of service (primitive.dev/terms)."New value: +"Acceptance of Primitive's terms of service (primitive.dev/terms) for the user, recorded on the new account."

changedOutput schema / description

Previous value: -"Envelope; the result is in data.data."New value: +"Envelope; see data."

changedOutput schema / properties / data / description

Previous value: -"API response; result in data."New value: +"New account in data; existing inbox fields here."

addedOutput schema / properties / data / properties / address

Added value: +{
+  "description": "Managed inbox domain.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / data / properties / api_key

Added value: +{
+  "description": "Null when it cannot be returned.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / data / properties / can_send_to

Added value: +{
+  "description": "Who you may email.",
+  "properties": {
+    "any_recipient": {
+      "description": "Any recipient is allowed.",
+      "type": "boolean"
+    },
+    "rules": {
+      "description": "Who is allowed: each has a type and a description.",
+      "type": "array"
+    },
+    "summary": {
+      "description": "What to tell the user.",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

changedOutput schema / properties / data / properties / data / properties / api_key / description

Previous value: -"Pass as api_key on later calls; absent if unavailable."New value: +"Pass as api_key on later calls."

removedOutput schema / properties / data / properties / data / properties / existing_account

Removed value: -{
-  "description": "This host's existing inbox, returned again.",
-  "type": "boolean"
-}

removedOutput schema / properties / data / properties / data / properties / message

Removed value: -{
-  "description": "For an existing inbox: what to tell the user.",
-  "type": "string"
-}

addedOutput schema / properties / data / properties / existing_account

Added value: +{
+  "description": "Existing inbox, returned again.",
+  "type": "boolean"
+}

addedOutput schema / properties / data / properties / message

Added value: +{
+  "description": "What to tell the user.",
+  "type": "string"
+}

addedOutput schema / properties / data / properties / org_id

Added value: +{
+  "description": "Account id.",
+  "type": "string"
+}

addedOutput schema / properties / data / properties / sender_address

Added value: +{
+  "description": "Mailbox to send from.",
+  "type": "string"
+}

Changed13 schema fields changedOct 21, 2026

changedInput schema / properties / terms_accepted / description

Previous value: -"Acceptance of Primitive's terms of service (primitive.dev/terms) for the user, recorded on the new account."New value: +"Confirms the user agrees to Primitive's terms of service (primitive.dev/terms)."

changedOutput schema / description

Previous value: -"Envelope; see data."New value: +"Envelope; the result is in data.data."

changedOutput schema / properties / data / description

Previous value: -"New account in data; existing inbox fields here."New value: +"API response; result in data."

removedOutput schema / properties / data / properties / address

Removed value: -{
-  "description": "Managed inbox domain.",
-  "type": [
-    "string",
-    "null"
-  ]
-}

removedOutput schema / properties / data / properties / api_key

Removed value: -{
-  "description": "Null when it cannot be returned.",
-  "type": [
-    "string",
-    "null"
-  ]
-}

removedOutput schema / properties / data / properties / can_send_to

Removed value: -{
-  "description": "Who you may email.",
-  "properties": {
-    "any_recipient": {
-      "description": "Any recipient is allowed.",
-      "type": "boolean"
-    },
-    "rules": {
-      "description": "Who is allowed: each has a type and a description.",
-      "type": "array"
-    },
-    "summary": {
-      "description": "What to tell the user.",
-      "type": "string"
-    }
-  },
-  "type": "object"
-}

changedOutput schema / properties / data / properties / data / properties / api_key / description

Previous value: -"Pass as api_key on later calls."New value: +"Pass as api_key on later calls; absent if unavailable."

addedOutput schema / properties / data / properties / data / properties / existing_account

Added value: +{
+  "description": "This host's existing inbox, returned again.",
+  "type": "boolean"
+}

addedOutput schema / properties / data / properties / data / properties / message

Added value: +{
+  "description": "For an existing inbox: what to tell the user.",
+  "type": "string"
+}

removedOutput schema / properties / data / properties / existing_account

Removed value: -{
-  "description": "Existing inbox, returned again.",
-  "type": "boolean"
-}

removedOutput schema / properties / data / properties / message

Removed value: -{
-  "description": "What to tell the user.",
-  "type": "string"
-}

removedOutput schema / properties / data / properties / org_id

Removed value: -{
-  "description": "Account id.",
-  "type": "string"
-}

removedOutput schema / properties / data / properties / sender_address

Removed value: -{
-  "description": "Mailbox to send from.",
-  "type": "string"
-}

Changed4 schema fields changedOct 21, 2026

changedOutput schema / description

Previous value: -"The managed inbox and its api_key."New value: +"Envelope; see data."

changedOutput schema / properties / data / description

Previous value: -"New account: under data. Existing inbox: here."New value: +"New account in data; existing inbox fields here."

addedOutput schema / properties / data / properties / data / description
```
Added value: +"The managed inbox and its api_key."
```
changedOutput schema / properties / data / properties / error / description
```
Previous value: -"Why refused."New value: +"Refusal: code, message."
```

Changed4 schema fields changedOct 21, 2026
- addedOutput schema / properties / data / properties / can_send_to / properties / any_recipient / description
```
Added value: +"Any recipient is allowed."
```
- addedOutput schema / properties / data / properties / can_send_to / properties / rules / description
```
Added value: +"Who is allowed: each has a type and a description."
```
- addedOutput schema / properties / data / properties / data / properties / can_send_to / properties / any_recipient / description
```
Added value: +"Any recipient is allowed."
```
- addedOutput schema / properties / data / properties / data / properties / can_send_to / properties / rules / description
```
Added value: +"Who is allowed: each has a type and a description."
```

Changed13 schema fields changedOct 20, 2026

changedInput schema / properties / device_name / description

Previous value: -"The app creating the account, such as ChatGPT, shown to the user later so they can tell where it came from."New value: +"Name of the app creating the account, such as ChatGPT. The user sees it later and recognises where the account came from."

changedInput schema / properties / terms_accepted / description

Previous value: -"The user's agreement to Primitive's terms of service, given on their behalf. Tell them you are agreeing to it."New value: +"Acceptance of Primitive's terms of service (primitive.dev/terms) for the user, recorded on the new account."

addedInput schema / properties / terms_accepted / type
```
Added value: +"boolean"
```

changedOutput schema / properties / data / properties / can_send_to / description

Previous value: -"Who you may email: summary, any_recipient, rules."New value: +"Who you may email."

addedOutput schema / properties / data / properties / can_send_to / properties

Added value: +{
+  "any_recipient": {
+    "type": "boolean"
+  },
+  "rules": {
+    "type": "array"
+  },
+  "summary": {
+    "description": "What to tell the user.",
+    "type": "string"
+  }
+}

changedOutput schema / properties / data / properties / data / properties / can_send_to / description

Previous value: -"Who you may email: summary, any_recipient, rules."New value: +"Who you may email."

addedOutput schema / properties / data / properties / data / properties / can_send_to / properties

Added value: +{
+  "any_recipient": {
+    "type": "boolean"
+  },
+  "rules": {
+    "type": "array"
+  },
+  "summary": {
+    "description": "What to tell the user.",
+    "type": "string"
+  }
+}

changedOutput schema / properties / data / properties / data / properties / funding / description
```
Previous value: -"Fund credits: url, description."New value: +"Link to fund credits."
```

addedOutput schema / properties / data / properties / data / properties / funding / properties

Added value: +{
+  "description": {
+    "type": "string"
+  },
+  "url": {
+    "type": [
+      "string",
+      "null"
+    ]
+  }
+}

changedOutput schema / properties / data / properties / data / properties / limits / description

Previous value: -"Caps: send_per_hour, send_per_day, api_per_minute."New value: +"What the plan allows."

addedOutput schema / properties / data / properties / data / properties / limits / properties

Added value: +{
+  "api_per_minute": {
+    "type": [
+      "number",
+      "string"
+    ]
+  },
+  "send_per_day": {
+    "type": [
+      "number",
+      "string"
+    ]
+  },
+  "send_per_hour": {
+    "type": [
+      "number",
+      "string"
+    ]
+  },
+  "storage_mb": {
+    "type": [
+      "number",
+      "string"
+    ]
+  }
+}

changedOutput schema / properties / data / properties / data / properties / upgrade / description

Previous value: -"Move to a full account: plan, description, claim_path."New value: +"How to move to a full account."

addedOutput schema / properties / data / properties / data / properties / upgrade / properties

Added value: +{
+  "claim_path": {
+    "type": "string"
+  },
+  "description": {
+    "type": "string"
+  },
+  "plan": {
+    "type": "string"
+  }
+}

Changed11 schema fields changedOct 20, 2026

changedInput schema / properties / device_name / description

Previous value: -"Where the account was created, such as ChatGPT, shown to the user later so they recognise it."New value: +"The app creating the account, such as ChatGPT, shown to the user later so they can tell where it came from."

changedInput schema / properties / terms_accepted / description

Previous value: -"Accepts Primitive's terms of service for the new account; tell the user you are accepting them."New value: +"The user's agreement to Primitive's terms of service, given on their behalf. Tell them you are agreeing to it."

changedOutput schema / properties / data / description

Previous value: -"API body."New value: +"New account: under data. Existing inbox: here."

changedOutput schema / properties / data / properties / can_send_to / description

Previous value: -"Allowed recipients."New value: +"Who you may email: summary, any_recipient, rules."

changedOutput schema / properties / data / properties / data / properties / can_send_to / description

Previous value: -"Allowed recipients."New value: +"Who you may email: summary, any_recipient, rules."

changedOutput schema / properties / data / properties / data / properties / funding / description
```
Previous value: -"Link to fund credits."New value: +"Fund credits: url, description."
```
addedOutput schema / properties / data / properties / data / properties / limits / description
```
Added value: +"Caps: send_per_hour, send_per_day, api_per_minute."
```
addedOutput schema / properties / data / properties / data / properties / org_id / description
```
Added value: +"Account id."
```
addedOutput schema / properties / data / properties / data / properties / plan / description
```
Added value: +"Plan name: agent."
```

changedOutput schema / properties / data / properties / data / properties / upgrade / description

Previous value: -"How to upgrade."New value: +"Move to a full account: plan, description, claim_path."

addedOutput schema / properties / data / properties / org_id / description
```
Added value: +"Account id."
```

Changed17 schema fields changedOct 20, 2026
- changedInput schema / properties / device_name / description
```
Previous value: -"Where the account was created, such as \"ChatGPT\", shown to the user later so they recognise it. Over 80 characters after trimming is refused."New value: +"Where the account was created, such as ChatGPT, shown to the user later so they recognise it."
```
- addedInput schema / properties / device_name / maxLength
```
Added value: +80
```
- changedInput schema / properties / terms_accepted / description
```
Previous value: -"Creating the account accepts Primitive's terms of service (https://www.primitive.dev/terms); tell the user rather than accepting silently for them."New value: +"Accepts Primitive's terms of service for the new account; tell the user you are accepting them."
```
- addedOutput schema / description
```
Added value: +"The managed inbox and its api_key."
```
- addedOutput schema / properties / data / description
```
Added value: +"API body."
```
- addedOutput schema / properties / data / properties / address / description
```
Added value: +"Managed inbox domain."
```
- addedOutput schema / properties / data / properties / can_send_to / description
```
Added value: +"Allowed recipients."
```
- addedOutput schema / properties / data / properties / data / properties / can_send_to / description
```
Added value: +"Allowed recipients."
```
- addedOutput schema / properties / data / properties / data / properties / funding
```
Added value: +{
+  "description": "Link to fund credits.",
+  "type": "object"
+}
```
- addedOutput schema / properties / data / properties / data / properties / sender_address / description
```
Added value: +"Mailbox to send from."
```
- changedOutput schema / properties / data / properties / data / properties / upgrade / description
```
Previous value: -"Link to a full account."New value: +"How to upgrade."
```
- addedOutput schema / properties / data / properties / error / description
```
Added value: +"Why refused."
```
- changedOutput schema / properties / data / properties / existing_account / description
```
Previous value: -"This host's existing inbox, returned again."New value: +"Existing inbox, returned again."
```
- addedOutput schema / properties / data / properties / message / description
```
Added value: +"What to tell the user."
```
- addedOutput schema / properties / data / properties / sender_address / description
```
Added value: +"Mailbox to send from."
```
- addedOutput schema / properties / data / properties / success / description
```
Added value: +"Accepted."
```
- addedOutput schema / properties / status / description
```
Added value: +"HTTP status."
```

Changed7 schema fields changedOct 20, 2026

changedInput schema / properties / device_name / description

Previous value: -"Optional label for where the account was created, e.g. \"ChatGPT\". Up to 80 characters once surrounding whitespace is removed. Shown to the user later so they can recognise this account."New value: +"Where the account was created, such as \"ChatGPT\", shown to the user later so they recognise it. Over 80 characters after trimming is refused."

changedInput schema / properties / terms_accepted / description

Previous value: -"Must be true. Creating the account accepts Primitive's terms of service (https://www.primitive.dev/terms); say so to the user rather than accepting silently on their behalf."New value: +"Creating the account accepts Primitive's terms of service (https://www.primitive.dev/terms); tell the user rather than accepting silently for them."

addedOutput schema / properties / data / properties / api_key / description
```
Added value: +"Null when it cannot be returned."
```
addedOutput schema / properties / data / properties / data / properties / address / description
```
Added value: +"Managed inbox domain."
```
addedOutput schema / properties / data / properties / data / properties / api_key / description
```
Added value: +"Pass as api_key on later calls."
```
addedOutput schema / properties / data / properties / data / properties / upgrade / description
```
Added value: +"Link to a full account."
```
addedOutput schema / properties / data / properties / existing_account / description
```
Added value: +"This host's existing inbox, returned again."
```

Changed4 schema fields changedOct 18, 2026

removedOutput schema / additionalProperties
```
Removed value: -false
```

addedOutput schema / properties / data / properties

Added value: +{
+  "address": {
+    "type": [
+      "string",
+      "null"
+    ]
+  },
+  "api_key": {
+    "type": [
+      "string",
+      "null"
+    ]
+  },
+  "can_send_to": {
+    "type": "object"
+  },
+  "data": {
+    "properties": {
+      "address": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "api_key": {
+        "type": "string"
+      },
+      "can_send_to": {
+        "type": "object"
+      },
+      "limits": {
+        "type": "object"
+      },
+      "org_id": {
+        "type": "string"
+      },
+      "plan": {
+        "type": "string"
+      },
+      "sender_address": {
+        "type": "string"
+      },
+      "upgrade": {
+        "type": "object"
+      }
+    },
+    "type": [
+      "object",
+      "null"
+    ]
+  },
+  "error": {},
+  "existing_account": {
+    "type": "boolean"
+  },
+  "message": {
+    "type": "string"
+  },
+  "org_id": {
+    "type": "string"
+  },
+  "sender_address": {
+    "type": "string"
+  },
+  "success": {
+    "type": "boolean"
+  }
+}

addedOutput schema / properties / data / type

Added value: +[
+  "object",
+  "string",
+  "null"
+]

removedOutput schema / properties / statusText
```
Removed value: -{
-  "type": "string"
-}
```

Changed4 schema fields changedOct 8, 2026

addedInput schema / properties / device_name

Added value: +{
+  "description": "Optional label for where the account was created, e.g. \"ChatGPT\". Up to 80 characters once surrounding whitespace is removed. Shown to the user later so they can recognise this account.",
+  "type": "string"
+}

removedInput schema / properties / requestBody

Removed value: -{
-  "additionalProperties": false,
-  "properties": {
-    "device_name": {
-      "description": "Optional label for where the account was created, e.g. \"ChatGPT\". Up to 80 characters once surrounding whitespace is removed. Shown to the user later so they can recognise this account.",
-      "type": "string"
-    },
-    "terms_accepted": {
-      "const": true,
-      "description": "Must be true. Creating the account accepts Primitive's terms of service (https://www.primitive.dev/terms); say so to the user rather than accepting silently on their behalf."
-    }
-  },
-  "required": [
-    "terms_accepted"
-  ],
-  "type": "object"
-}

addedInput schema / properties / terms_accepted

Added value: +{
+  "const": true,
+  "description": "Must be true. Creating the account accepts Primitive's terms of service (https://www.primitive.dev/terms); say so to the user rather than accepting silently on their behalf."
+}

changedInput schema / required

Previous value: -[
-  "requestBody"
-]New value: +[
+  "terms_accepted"
+]

AddedAug 13, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations only state readOnly=false, destructive=false, idempotent=false, and openWorld=false, so the safety profile is thin. The description adds the behavior that matters: creation implies accepting the terms on the user's behalf, an existing inbox returns existing_account:true and should be reported as the user's inbox, the returned api_key must be passed verbatim on later calls, and can_send_to constrains recipients. That is substantive behavioral context beyond what the annotations already declare.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and the call-first rule are stated first, then operational details follow in short clauses, so nothing is buried. The final 'Result:' sentence largely restates fields already covered by the output schema, which is mild redundancy, but the other sentences pay for their place by covering the api_key lifecycle, what to report to the user, and the recipient restrictions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutating account-creation tool with a terms-acceptance flag, this definition covers what is created, what is returned, how to handle the idempotent-ish existing-account case, how the api_key is used later, and what to tell the user. Nothing an agent would need in order to call it correctly, or to explain the result to the user, is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema documents both parameters at 100% coverage, so the baseline would be 3. The description adds meaning by explaining that creating the account accepts the terms for the user, which requires telling the user, and by clarifying that 'address' is a domain rather than a mailbox and that sender_address is the mailbox sendEmail uses. It does not discuss device_name, but the schema already explains that parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource, 'Create an email account ... and get its api_key', which clearly separates this tool from the sibling set of sending, reading, and searching email tools. It also explains the downstream purpose, namely that this account's api_key is needed for the later email calls.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states the exact trigger ('call this first when you have no Primitive API key and the user wants to send or receive email') and the alternative path ('Without an api_key the user must sign in'). It also specifies what to tell the user about account creation and the terms of service, so the prerequisites are not left for inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All email tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?