Permissions

1
from agentmail import AgentMail
2
3
client = AgentMail(api_key="YOUR_API_KEY")
4
5
key = client.api_keys.create(
6
    name="read-only-agent",
7
    permissions={
8
        "inbox_read": True,
9
        "thread_read": True,
10
        "message_read": True,
11
        "draft_read": True,
12
        "webhook_read": True,
13
        "domain_read": True,
14
        "list_entry_read": True,
15
        "metrics_read": True,
16
        "api_key_read": True,
17
        "pod_read": True,
18
        "label_spam_read": True,
19
        "label_blocked_read": True,
20
        "label_trash_read": True,
21
    }
22
)
23
24
print(key.api_key)

1
key = client.api_keys.create(
2
    name="clean-inbox-agent",
3
    permissions={
4
        "inbox_read": True,
5
        "inbox_create": True,
6
        "inbox_update": True,
7
        "inbox_delete": True,
8
        "thread_read": True,
9
        "thread_delete": True,
10
        "message_read": True,
11
        "message_send": True,
12
        "message_update": True,
13
        "label_spam_read": False,
14
        "label_blocked_read": False,
15
        "label_trash_read": False,
16
        "draft_read": True,
17
        "draft_create": True,
18
        "draft_update": True,
19
        "draft_delete": True,
20
        "draft_send": True,
21
        "webhook_read": True,
22
        "webhook_create": True,
23
        "webhook_update": True,
24
        "webhook_delete": True,
25
        "domain_read": True,
26
        "domain_create": True,
27
        "domain_update": True,
28
        "domain_delete": True,
29
        "list_entry_read": True,
30
        "list_entry_create": True,
31
        "list_entry_delete": True,
32
        "metrics_read": True,
33
        "api_key_read": True,
34
        "api_key_create": True,
35
        "api_key_delete": True,
36
        "pod_read": True,
37
        "pod_create": True,
38
        "pod_delete": True,
39
    }
40
)

1
"""
2
AgentMail Permissions — copy into Cursor/Claude.
3
4
Permissions are a whitelist on API keys. No `permissions` field = full access.
5
When `permissions` is set, only `True` values are granted; omitted or `False` = denied.
6
Permissions intersect with scope (pod/inbox). A restricted key cannot create a more privileged child key.
7
8
Permission fields (all optional<bool>, resource_action format):
9
  Inboxes: inbox_read, inbox_create, inbox_update, inbox_delete
10
  Threads: thread_read, thread_delete
11
  Messages: message_read, message_send, message_update
12
  Label visibility: label_spam_read, label_blocked_read, label_trash_read
13
  Drafts: draft_read, draft_create, draft_update, draft_delete, draft_send
14
  Webhooks: webhook_read, webhook_create, webhook_update, webhook_delete
15
  Domains: domain_read, domain_create, domain_update, domain_delete
16
  Lists: list_entry_read, list_entry_create, list_entry_delete
17
  Metrics: metrics_read
18
  API Keys: api_key_read, api_key_create, api_key_delete
19
  Pods: pod_read, pod_create, pod_delete
20
21
API: api_keys.create(name, permissions={...})
22
"""
23
from agentmail import AgentMail
24
25
client = AgentMail(api_key="YOUR_API_KEY")
26
27
# read-only key
28
key = client.api_keys.create(
29
    name="read-only",
30
    permissions={"inbox_read": True, "message_read": True, "thread_read": True}
31
)
32
print(key.api_key)