agentmail

Name: agentmail
Author: sickn33

44kstars6.5kforks

How to install agentmail?

sickn33/agentic-awesome-skills/agentmail

$npx -y skills add sickn33/agentic-awesome-skills --skill agentmail

Installs into the current project.

Summary

Email infrastructure for AI agents. Create accounts, send/receive emails, manage webhooks, and check karma balance via the AgentMail API.

Files · 1

View on GitHub

SKILL.md

1	# AgentMail — Email for AI Agents
2
3	AgentMail gives AI agents real email addresses (`@theagentmail.net`) with a REST API. Agents can send and receive email, sign up for services (GitHub, AWS, Slack, etc.), and get verification codes. A karma system prevents spam and keeps the shared domain's reputation high.
4
5	Base URL: `https://api.theagentmail.net`
6
7	## When to Use
8	- An AI agent needs a real inbox/outbox for signups, verification flows, or transactional communication.
9	- You need to provision AgentMail accounts, send messages, read inbox contents, or register inbound webhooks.
10	- You need to monitor karma usage or wire email events into agent automation.
11
12	## Quick start
13
14	All requests require `Authorization: Bearer am_...` header (API key from dashboard).
15
16	### Create an email account (-10 karma)
17
18	```bash
19	curl -X POST https://api.theagentmail.net/v1/accounts \
20	-H "Authorization: Bearer am_..." \
21	-H "Content-Type: application/json" \
22	-d '{"address": "my-agent@theagentmail.net"}'
23	```
24
25	Response: `{"data": {"id": "...", "address": "my-agent@theagentmail.net", "displayName": null, "createdAt": 123}}`
26
27	### Send email (-1 karma)
28
29	```bash
30	curl -X POST https://api.theagentmail.net/v1/accounts/{accountId}/messages \
31	-H "Authorization: Bearer am_..." \
32	-H "Content-Type: application/json" \
33	-d '{
34	"to": ["recipient@example.com"],
35	"subject": "Hello from my agent",
36	"text": "Plain text body",
37	"html": "<p>Optional HTML body</p>"
38	}'
39	```
40
41	Optional fields: `cc`, `bcc` (string arrays), `inReplyTo`, `references` (strings for threading), `attachments` (array of `{filename, contentType, content}` where content is base64).
42
43	### Read inbox
44
45	```bash
46	# List messages
47	curl https://api.theagentmail.net/v1/accounts/{accountId}/messages \
48	-H "Authorization: Bearer am_..."
49
50	# Get full message (with body and attachments)
51	curl https://api.theagentmail.net/v1/accounts/{accountId}/messages/{messageId} \
52	-H "Authorization: Bearer am_..."
53	```
54
55	### Check karma
56
57	```bash
58	curl https://api.theagentmail.net/v1/karma \
59	-H "Authorization: Bearer am_..."
60	```
61
62	Response: `{"data": {"balance": 90, "events": [...]}}`
63
64	### Register webhook (real-time inbound)
65
66	```bash
67	curl -X POST https://api.theagentmail.net/v1/accounts/{accountId}/webhooks \
68	-H "Authorization: Bearer am_..." \
69	-H "Content-Type: application/json" \
70	-d '{"url": "https://my-agent.example.com/inbox"}'
71	```
72
73	Webhook deliveries include two security headers:
74	- `X-AgentMail-Signature` -- HMAC-SHA256 hex digest of the request body, signed with the webhook secret
75	- `X-AgentMail-Timestamp` -- millisecond timestamp of when the delivery was sent
76
77	Verify the signature and reject requests with timestamps older than 5 minutes to prevent replay attacks:
78
79	```typescript
80	import { createHmac } from "crypto";
81
82	const verifyWebhook = (body: string, signature: string, timestamp: string, secret: string) => {
83	if (Date.now() - Number(timestamp) > 5 * 60 * 1000) return false;
84	return createHmac("sha256", secret).update(body).digest("hex") === signature;
85	};
86	```
87
88	### Download attachment
89
90	```bash
91	curl https://api.theagentmail.net/v1/accounts/{accountId}/messages/{messageId}/attachments/{attachmentId} \
92	-H "Authorization: Bearer am_..."
93	```
94
95	Returns `{"data": {"url": "https://signed-download-url..."}}`.
96
97	## Full API reference
98
99	\| Method \| Path \| Description \| Karma \|
100	\|--------\|------\|-------------\|-------\|
101	\| POST \| `/v1/accounts` \| Create email account \| -10 \|
102	\| GET \| `/v1/accounts` \| List all accounts \| \|
103	\| GET \| `/v1/accounts/:id` \| Get account details \| \|
104	\| DELETE \| `/v1/accounts/:id` \| Delete account \| +10 \|
105	\| POST \| `/v1/accounts/:id/messages` \| Send email \| -1 \|
106	\| GET \| `/v1/accounts/:id/messages` \| List messages \| \|
107	\| GET \| `/v1/accounts/:id/messages/:msgId` \| Get full message \| \|
108	\| GET \| `/v1/accounts/:id/messages/:msgId/attachments/:attId` \| Get attachment URL \| \|
109	\| POST \| `/v1/accounts/:id/webhooks` \| Register webhook \| \|
110	\| GET \| `/v1/accounts/:id/webhooks` \| List webhooks \| \|
111	\| DELETE \| `/v1/accounts/:id/webhooks/:whId` \| Delete webhook \| \|
112	\| GET \| `/v1/karma` \| Get balance + events \| \|
113
114	## Karma system
115
116	Every action has a karma cost or reward:
117
118	\| Event \| Karma \| Why \|
119	\|---\|---\|---\|
120	\| `money_paid` \| +100 \| Purchase credits \|
121	\| `email_received` \| +2 \| Someone replied from a trusted domain \|
122	\| `account_deleted` \| +10 \| Karma refunded when you delete an address \|
123	\| `email_sent` \| -1 \| Sending costs karma \|
124	\| `account_created` \| -10 \| Creating addresses costs karma \|
125
126	Important rules:
127	- Karma is only awarded for inbound emails from trusted providers (Gmail, Outlook, Yahoo, iCloud, ProtonMail, Fastmail, Hey, etc.). Emails from unknown/throwaway domains don't earn karma.
128	- You only earn karma once per sender until the agent replies. If sender X emails you 5 times without a r

People who liked this also viewed

6 picks

Type

agentmail

44kstars6.5kforks

View on GitHub

How to install agentmail?

sickn33/agentic-awesome-skills/agentmail

$npx -y skills add sickn33/agentic-awesome-skills --skill agentmail

Installs into the current project.

Summary

Email infrastructure for AI agents. Create accounts, send/receive emails, manage webhooks, and check karma balance via the AgentMail API.

Files · 1

View on GitHub

SKILL.md

1	# AgentMail — Email for AI Agents
2
3	AgentMail gives AI agents real email addresses (`@theagentmail.net`) with a REST API. Agents can send and receive email, sign up for services (GitHub, AWS, Slack, etc.), and get verification codes. A karma system prevents spam and keeps the shared domain's reputation high.
4
5	Base URL: `https://api.theagentmail.net`
6
7	## When to Use
8	- An AI agent needs a real inbox/outbox for signups, verification flows, or transactional communication.
9	- You need to provision AgentMail accounts, send messages, read inbox contents, or register inbound webhooks.
10	- You need to monitor karma usage or wire email events into agent automation.
11
12	## Quick start
13
14	All requests require `Authorization: Bearer am_...` header (API key from dashboard).
15
16	### Create an email account (-10 karma)
17
18	```bash
19	curl -X POST https://api.theagentmail.net/v1/accounts \
20	-H "Authorization: Bearer am_..." \
21	-H "Content-Type: application/json" \
22	-d '{"address": "my-agent@theagentmail.net"}'
23	```
24
25	Response: `{"data": {"id": "...", "address": "my-agent@theagentmail.net", "displayName": null, "createdAt": 123}}`
26
27	### Send email (-1 karma)
28
29	```bash
30	curl -X POST https://api.theagentmail.net/v1/accounts/{accountId}/messages \
31	-H "Authorization: Bearer am_..." \
32	-H "Content-Type: application/json" \
33	-d '{
34	"to": ["recipient@example.com"],
35	"subject": "Hello from my agent",
36	"text": "Plain text body",
37	"html": "<p>Optional HTML body</p>"
38	}'
39	```
40
41	Optional fields: `cc`, `bcc` (string arrays), `inReplyTo`, `references` (strings for threading), `attachments` (array of `{filename, contentType, content}` where content is base64).
42
43	### Read inbox
44
45	```bash
46	# List messages
47	curl https://api.theagentmail.net/v1/accounts/{accountId}/messages \
48	-H "Authorization: Bearer am_..."
49
50	# Get full message (with body and attachments)
51	curl https://api.theagentmail.net/v1/accounts/{accountId}/messages/{messageId} \
52	-H "Authorization: Bearer am_..."
53	```
54
55	### Check karma
56
57	```bash
58	curl https://api.theagentmail.net/v1/karma \
59	-H "Authorization: Bearer am_..."
60	```
61
62	Response: `{"data": {"balance": 90, "events": [...]}}`
63
64	### Register webhook (real-time inbound)
65
66	```bash
67	curl -X POST https://api.theagentmail.net/v1/accounts/{accountId}/webhooks \
68	-H "Authorization: Bearer am_..." \
69	-H "Content-Type: application/json" \
70	-d '{"url": "https://my-agent.example.com/inbox"}'
71	```
72
73	Webhook deliveries include two security headers:
74	- `X-AgentMail-Signature` -- HMAC-SHA256 hex digest of the request body, signed with the webhook secret
75	- `X-AgentMail-Timestamp` -- millisecond timestamp of when the delivery was sent
76
77	Verify the signature and reject requests with timestamps older than 5 minutes to prevent replay attacks:
78
79	```typescript
80	import { createHmac } from "crypto";
81
82	const verifyWebhook = (body: string, signature: string, timestamp: string, secret: string) => {
83	if (Date.now() - Number(timestamp) > 5 * 60 * 1000) return false;
84	return createHmac("sha256", secret).update(body).digest("hex") === signature;
85	};
86	```
87
88	### Download attachment
89
90	```bash
91	curl https://api.theagentmail.net/v1/accounts/{accountId}/messages/{messageId}/attachments/{attachmentId} \
92	-H "Authorization: Bearer am_..."
93	```
94
95	Returns `{"data": {"url": "https://signed-download-url..."}}`.
96
97	## Full API reference
98
99	\| Method \| Path \| Description \| Karma \|
100	\|--------\|------\|-------------\|-------\|
101	\| POST \| `/v1/accounts` \| Create email account \| -10 \|
102	\| GET \| `/v1/accounts` \| List all accounts \| \|
103	\| GET \| `/v1/accounts/:id` \| Get account details \| \|
104	\| DELETE \| `/v1/accounts/:id` \| Delete account \| +10 \|
105	\| POST \| `/v1/accounts/:id/messages` \| Send email \| -1 \|
106	\| GET \| `/v1/accounts/:id/messages` \| List messages \| \|
107	\| GET \| `/v1/accounts/:id/messages/:msgId` \| Get full message \| \|
108	\| GET \| `/v1/accounts/:id/messages/:msgId/attachments/:attId` \| Get attachment URL \| \|
109	\| POST \| `/v1/accounts/:id/webhooks` \| Register webhook \| \|
110	\| GET \| `/v1/accounts/:id/webhooks` \| List webhooks \| \|
111	\| DELETE \| `/v1/accounts/:id/webhooks/:whId` \| Delete webhook \| \|
112	\| GET \| `/v1/karma` \| Get balance + events \| \|
113
114	## Karma system
115
116	Every action has a karma cost or reward:
117
118	\| Event \| Karma \| Why \|
119	\|---\|---\|---\|
120	\| `money_paid` \| +100 \| Purchase credits \|
121	\| `email_received` \| +2 \| Someone replied from a trusted domain \|
122	\| `account_deleted` \| +10 \| Karma refunded when you delete an address \|
123	\| `email_sent` \| -1 \| Sending costs karma \|
124	\| `account_created` \| -10 \| Creating addresses costs karma \|
125
126	Important rules:
127	- Karma is only awarded for inbound emails from trusted providers (Gmail, Outlook, Yahoo, iCloud, ProtonMail, Fastmail, Hey, etc.). Emails from unknown/throwaway domains don't earn karma.
128	- You only earn karma once per sender until the agent replies. If sender X emails you 5 times without a r

People who liked this also viewed

6 picks

Type