{"id":"5fa892ee-5f79-43d7-b3fa-c6862cb889c2","entityType":"agent","slug":"clawhub-oyagev-mailgi","name":"Mailgi — Free Email for Agents","canonicalUrl":"https://www.xpersona.co/agent/clawhub-oyagev-mailgi","canonicalPath":"/agent/clawhub-oyagev-mailgi","generatedAt":"2026-10-11T14:14:07.051Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T11:37:44.138Z","emptyReason":null},"description":"Give an AI agent a real, deliverable email address. Register in one POST with no OAuth and no signup form, then send, receive, read and organise mail over a plain REST API — on a shared handle or your own verified domain. Skill: Mailgi — Free Email for Agents Owner: oyagev Summary: Give an AI agent a real, deliverable email address. Register in one POST with no OAuth and no signup form, then send, receive, read and organise mail over a plain REST API — on a shared handle or your own verified domain. Tags: latest:1.1.0 Version history: v1.1.0 | 2026-08-30T11:55:25.886Z | user Rewritten against the live API. Removes DID authentication a","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s170q04698qp4kcr0jzqt3bejs851p1t:mailgi","sourceUrl":"https://clawhub.ai/oyagev/mailgi","homepage":"https://clawhub.ai/oyagev/skills/mailgi","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/oyagev/mailgi","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/oyagev/skills/mailgi","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":61,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Give an AI agent a real, deliverable email address. Register in one POST with no OAuth and no signup form, then send, receive, read and organise mail over a pla"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T11:37:44.138Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T11:37:44.138Z","emptyReason":null},"stars":null,"forks":null,"downloads":1074,"packageName":null,"latestVersion":"1.1.0","tractionLabel":"1.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T11:37:44.081Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T11:37:44.138Z","lastCrawledAt":"2026-10-11T11:37:44.081Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T11:37:44.081Z","lastVerifiedAt":null,"highlights":[{"version":"1.1.0","createdAt":"2026-08-30T11:55:25.886Z","changelog":"Rewritten against the live API. Removes DID authentication and blockchain billing, neither of which works: the DID challenge/response returns a token that no endpoint accepts, and there is no billing in the send path. Documents DELETE /v1/agents/me, which is permanent and burns the address, plus mailbox rename and delete. States the real limits: 100/day per API key, 300/day per agent, per-org caps that rise with domain age. Adds the things agents assume and we do not have: no attachments, no search, no webhooks or WebSocket push. Notes the provisioning race right after register.","fileCount":3,"zipByteSize":7283},{"version":"1.0.2","createdAt":"2026-04-21T04:00:42.968Z","changelog":"**Summary: Sending is now always free. Billing removed.** - Sending emails is now always free, with a daily rate limit of 100 external emails per API key. - Error documentation updated: HTTP 429 error (`rate limit exceeded`) added. - Minor clarifications and updates to CLI and SDK usage examples.","fileCount":3,"zipByteSize":4657},{"version":"1.0.1","createdAt":"2026-04-18T15:09:11.278Z","changelog":"- Added section 11: TypeScript / Node.js SDK usage instructions, including setup, registration, sending and reading email, error handling, and balance check. - Added section 12: CLI usage documentation with installation steps and command examples for agent registration, login, inbox management, and email sending. - No changes to the API or core documentation for REST usage.","fileCount":2,"zipByteSize":3868},{"version":"1.0.0","createdAt":"2026-04-17T22:46:44.708Z","changelog":"mailgi-email-for-agents 1.0.0 - Free Agent-first, full email via API - Provides endpoints to register agents, send and receive emails via API. - Supports mailbox management, billing, and API key creation. - Includes DID-based authentication as an option. - Offers clear instructions and quick start examples for setup.","fileCount":2,"zipByteSize":2859}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s170q04698qp4kcr0jzqt3bejs851p1t:mailgi","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-oyagev-mailgi/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-oyagev-mailgi/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-oyagev-mailgi/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-oyagev-mailgi/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-oyagev-mailgi/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-oyagev-mailgi/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T14:14:07.050Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-oyagev-mailgi/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-oyagev-mailgi/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-oyagev-mailgi/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-oyagev-mailgi/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T11:37:44.138Z","emptyReason":null},"readme":"Skill: Mailgi — Free Email for Agents\n\nOwner: oyagev\n\nSummary: Give an AI agent a real, deliverable email address. Register in one POST with no OAuth and no signup form, then send, receive, read and organise mail over a plain REST API — on a shared handle or your own verified domain.\n\nTags: latest:1.1.0\n\nVersion history:\n\nv1.1.0 | 2026-08-30T11:55:25.886Z | user\n\nRewritten against the live API. Removes DID authentication and blockchain billing, neither of which works: the DID challenge/response returns a token that no endpoint accepts, and there is no billing in the send path. Documents DELETE /v1/agents/me, which is permanent and burns the address, plus mailbox rename and delete. States the real limits: 100/day per API key, 300/day per agent, per-org caps that rise with domain age. Adds the things agents assume and we do not have: no attachments, no search, no webhooks or WebSocket push. Notes the provisioning race right after register.\n\nv1.0.2 | 2026-04-21T04:00:42.968Z | user\n\n**Summary: Sending is now always free. Billing removed.**\n\n- Sending emails is now always free, with a daily rate limit of 100 external emails per API key.\n- Error documentation updated: HTTP 429 error (`rate limit exceeded`) added.\n- Minor clarifications and updates to CLI and SDK usage examples.\n\nv1.0.1 | 2026-04-18T15:09:11.278Z | user\n\n- Added section 11: TypeScript / Node.js SDK usage instructions, including setup, registration, sending and reading email, error handling, and balance check.\n- Added section 12: CLI usage documentation with installation steps and command examples for agent registration, login, inbox management, and email sending.\n- No changes to the API or core documentation for REST usage.\n\nv1.0.0 | 2026-04-17T22:46:44.708Z | user\n\nmailgi-email-for-agents 1.0.0\n\n- Free Agent-first, full email via API\n- Provides endpoints to register agents, send and receive emails via API.\n- Supports mailbox management, billing, and API key creation.\n- Includes DID-based authentication as an option.\n- Offers clear instructions and quick start examples for setup.\n\nArchive index:\n\nArchive v1.1.0: 3 files, 7283 bytes\n\nFiles: skill-card.md (2483b), SKILL.md (13361b), _meta.json (125b)\n\nFile v1.1.0:SKILL.md\n\n---\nname: mailgi\ndescription: Give an AI agent a real, deliverable email address. Register in one POST with no OAuth and no signup form, then send, receive, read and organise mail over a plain REST API — on a shared handle or your own verified domain.\nversion: 1.1.0\nhomepage: https://www.mailgi.xyz\nmetadata:\n openclaw:\n emoji: \"📬\"\n envVars:\n - name: MAILGI_API_KEY\n required: false\n description: An existing Mailgi API key. Not needed to get started — an agent registers with no credentials at all and stores the key it gets back.\n---\n\n# mailgi — SKILL FILE\n\nThis file teaches you how to use the mailgi email API.\nYou are an AI agent. Read this file, then you can send and receive email.\n\n**Skill version 1.1.0 · updated 2026-08-30**\nCanonical copy: https://www.mailgi.xyz/SKILL.md — if yours is older, re-fetch it.\nThis file tracks the live API; a stale copy will describe endpoints that changed.\n\n**Base URL:** `https://api.mailgi.xyz`\n**Auth:** `Authorization: Bearer ` on all authenticated requests.\n\n---\n\n## 1. Get an email address\n\nRegister once. No password, no OAuth.\n\n```\nPOST /v1/agents/register\nContent-Type: application/json\n\n{ \"label\": \"my-agent\" }\n```\n\nOptional fields:\n- `label` — a name for your own reference; shows up in the owner's dashboard.\n- `did` — a W3C DID in `did:key:` format. Only affects which deterministic\n alias you get. It does **not** enable password-free login (see section 7).\n\nResponse:\n```json\n{\n \"agentId\": \"clxxx...\",\n \"emailAddress\": \"buzzing-falcon@mailgi.xyz\",\n \"aliasAddress\": \"x7k3mwf2qr5b@mailgi.xyz\",\n \"apiKey\": \"amb_...\",\n \"apiKeyId\": \"clyyy...\"\n}\n```\n\n**Store `apiKey` immediately. It is shown exactly once.**\n\n`emailAddress` is your friendly address. Use it for sending and tell others to send to it.\n`aliasAddress` is a deterministic alias — both receive mail to the same inbox.\n\n---\n\n## 2. Check your profile\n\n```\nGET /v1/agents/me\nAuthorization: Bearer \n```\n\n---\n\n## 3. Read your inbox\n\n```\nGET /v1/mail\nAuthorization: Bearer \n```\n\nOptional query params:\n- `mailboxId` — restrict to one folder\n- `limit` — max results (default 20, max 100)\n- `position` — pagination offset (default 0)\n- `sort` — `asc` or `desc` (default `desc`)\n\n**There is no search.** No full-text, subject, sender or date filtering exists —\nany other query param is ignored, not rejected. To find a message, page through\nthe list and match it yourself.\n\nResponse: `{ messages: [...], total: N, position: N }`\n\nEach message has: `id`, `subject`, `from`, `to`, `receivedAt`, `preview`, `seen`.\n\n**There is no push delivery.** No webhooks, no WebSocket, no long-poll. The only\nway to learn about new mail is to call `GET /v1/mail` again. Poll every few\nseconds when waiting for something specific (a verification code), and every\nminute or two for a background inbox.\n\n**Get full body of a message:**\n\n```\nGET /v1/mail/\nAuthorization: Bearer \n```\n\nResponse includes `htmlBody` and/or `textBody`. If body is a string, use it directly.\nIf it is an array of JMAP parts, look up `bodyValues[part.partId].value` for the text.\n\n---\n\n## 4. Send email\n\n```\nPOST /v1/mail/send\nAuthorization: Bearer \nContent-Type: application/json\n\n{\n \"to\": [\"someone@example.com\"],\n \"subject\": \"Hello from my agent\",\n \"textBody\": \"Hi there.\"\n}\n```\n\nOptional fields: `cc`, `bcc`, `htmlBody`, `replyTo`.\n`to`, `cc`, `bcc` accept a single string or an array of strings.\n\nResponse: `{ \"messageId\": \"...\" }`\n\nSending is free. Rate limit: 100 external emails per day per API key, plus\n50/hour and 300/day per agent across all its keys. On a custom domain your\norganisation is also capped by domain age: 100/day under three days, 1000/day\nup to thirty, 5000/day after that.\n\n**Attachments are not supported.** There is no `attachments` field — sending one\ndoes nothing. Send links instead.\n\n**Sending right after registering can fail.** The mailbox is provisioned\nasynchronously; wait a couple of seconds after `register` before your first\nsend, and retry once on a 5xx.\n\n---\n\n## 5. Manage mailboxes (folders)\n\nList folders:\n```\nGET /v1/mailboxes\nAuthorization: Bearer \n```\n\nEach mailbox has `id`, `name`, `role` (inbox/sent/trash/drafts/etc), `totalEmails`, `unreadEmails`.\n\nCreate a folder:\n```\nPOST /v1/mailboxes\nAuthorization: Bearer \nContent-Type: application/json\n\n{ \"name\": \"Projects\", \"parentId\": \"\" }\n```\n\nMove a message to a folder:\n```\nPATCH /v1/mail//move\nAuthorization: Bearer \nContent-Type: application/json\n\n{ \"mailboxId\": \"\" }\n```\n\nMark as read:\n```\nPATCH /v1/mail//flags\nAuthorization: Bearer \nContent-Type: application/json\n\n{ \"seen\": true }\n```\n\nRename a folder:\n```\nPATCH /v1/mailboxes/\nAuthorization: Bearer \nContent-Type: application/json\n\n{ \"name\": \"Archive\" }\n```\n\nDelete a folder:\n```\nDELETE /v1/mailboxes/\nAuthorization: Bearer \n```\n\nDelete a message (moves to Trash):\n```\nDELETE /v1/mail/\nAuthorization: Bearer \n```\n\n---\n\n## 6. API keys\n\nYou can create additional API keys (e.g. one per task):\n\n```\nPOST /v1/apikeys\nAuthorization: Bearer \nContent-Type: application/json\n\n{ \"label\": \"task-runner\", \"expiresAt\": \"2026-12-31T00:00:00Z\" }\n```\n\nResponse includes `apiKey` (raw, shown once) and `id`.\n\nList keys: `GET /v1/apikeys`\nRevoke a key: `DELETE /v1/apikeys/`\n\n---\n\n## 7. DID-based auth — NOT AVAILABLE YET\n\n**Do not use this. Use your API key.**\n\n`POST /v1/auth/challenge` and `POST /v1/auth/verify` exist and will return a\nsigned token, but **no endpoint accepts that token yet** — authentication is\nAPI-key-only today, so the token returns `401` everywhere. Registering with a\n`did:key:` DID is supported and does determine your alias address; the\nchallenge/response login it implies does not work.\n\nThis section will describe the real flow once it does.\n\n---\n\n## 8. Error responses\n\nAll errors follow:\n```json\n{ \"error\": { \"code\": \"ERROR_CODE\", \"message\": \"Human-readable description\" } }\n```\n\nCommon codes:\n- `401` — missing or invalid API key\n- `404` — message or mailbox not found\n- `409` — conflict (e.g. mailbox name already exists)\n- `RATE_LIMITED` — rate limit exceeded\n\n**Match on `error.code`, not on the HTTP status.** Rate limiting currently\nreturns `429` on some paths and `500` on others; the `code` is reliable where\nthe status is not.\n\n---\n\n## 9. Deleting your account\n\n```\nDELETE /v1/agents/me\nAuthorization: Bearer \n```\n\nRevokes every API key and removes the mailbox. Returns `204`.\n\n**This is permanent, and it burns the address.** A deleted address can never be\nregistered again — not by you, not by anyone. There is no undo and no support\npath to reverse it. Do not call this to \"reset\" or \"start clean\": register a\nsecond agent instead and simply stop using the first.\n\n---\n\n## 10. Health\n\n```\nGET /health — liveness (always 200 if server is up)\nGET /health/ready — readiness (checks DB + mail server)\n```\n\n---\n\n## Quick start (copy-paste)\n\n```bash\n# 1. Register\nRESP=$(curl -s -X POST https://api.mailgi.xyz/v1/agents/register \\\n -H \"Content-Type: application/json\" \\\n -d '{\"label\":\"my-agent\"}')\nEMAIL=$(echo $RESP | jq -r .emailAddress)\nKEY=$(echo $RESP | jq -r .apiKey)\n\n# 2. Send a message.\n# Give the mailbox a moment first — sending in the same breath as registering\n# can 500 while the mail server finishes provisioning. Retry once if it does.\nsleep 3\ncurl -s -X POST https://api.mailgi.xyz/v1/mail/send \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d \"{\\\"to\\\":[\\\"someone@example.com\\\"],\\\"subject\\\":\\\"Hi\\\",\\\"textBody\\\":\\\"Hello from $EMAIL\\\"}\"\n\n# 3. Read inbox\ncurl -s https://api.mailgi.xyz/v1/mail \\\n -H \"Authorization: Bearer $KEY\"\n```\n\n---\n\n## 11. TypeScript / Node.js SDK\n\nInstall:\n```bash\nnpm install @mailgi/mailgi\n```\n\n```typescript\nimport { AgentMailboxClient } from '@mailgi/mailgi';\n\n// Construct from a stored API key\nconst client = AgentMailboxClient.withApiKey(\n 'https://api.mailgi.xyz',\n process.env.MAILGI_API_KEY!,\n);\n\n// Register a new agent (first time only — save the returned apiKey)\nconst reg = await client.agents.register({ label: 'my-agent' });\n// reg.emailAddress => 'buzzing-falcon@mailgi.xyz'\n// reg.apiKey => 'amb_...' (shown once — store it)\nclient.apiKey = reg.apiKey;\n\n// Send email\nconst { messageId } = await client.mail.send({\n to: ['someone@example.com'],\n subject: 'Hello',\n textBody: 'Hi from my agent.',\n});\n\n// Read inbox\nconst { messages } = await client.mail.list({ limit: 20, sort: 'desc' });\nconst email = await client.mail.get(messages[0].id);\nconsole.log(email.subject, email.textBody);\n\n// Mark as read\nawait client.mail.setFlags(email.id, { seen: true });\n```\n\nAll SDK methods map 1-to-1 to the REST endpoints above. Errors extend `AgentMailboxError` with `statusCode` and `code`:\n\n```typescript\nimport { NotFoundError, UnauthorizedError } from '@mailgi/mailgi';\n\ntry {\n await client.mail.get('bad-id');\n} catch (err) {\n if (err instanceof NotFoundError) console.error('Not found');\n if (err instanceof UnauthorizedError) console.error('Bad API key');\n}\n```\n\n---\n\n## 12. CLI\n\nInstall globally:\n```bash\nnpm install -g @mailgi/mailgi\n```\n\nAll commands require `--agent `.\n\n```bash\n# Register a new agent (saves API key to ~/.mailgi/config.json)\nmailgi register --label my-agent --agent me@mailgi.xyz\n\n# Save an existing agent by API key\nmailgi login --agent buzzing-falcon@mailgi.xyz --apikey amb_...\n\n# List saved agents\nmailgi agents\n\n# Show agent profile (live from API)\nmailgi me --agent buzzing-falcon\n\n# Read inbox\nmailgi inbox --agent buzzing-falcon\nmailgi inbox --agent buzzing-falcon --limit 50\n\n# Read a message (auto-marks as seen)\nmailgi read --agent buzzing-falcon \n\n# Send email\nmailgi send --agent buzzing-falcon --to alice@example.com --subject \"Hi\" --body \"Hello\"\nmailgi send --agent buzzing-falcon --to alice@example.com --subject \"Hi\" --body-file ./message.txt\n\n# Delete a message\nmailgi delete --agent buzzing-falcon \n\n# Mailboxes\nmailgi mailboxes --agent buzzing-falcon\nmailgi mailboxes create \"Projects\" --agent buzzing-falcon\nmailgi mailboxes delete --agent buzzing-falcon\n\n# API keys\nmailgi keys --agent buzzing-falcon\nmailgi keys create --label task-key --agent buzzing-falcon\nmailgi keys revoke --agent buzzing-falcon\n\n# Config\nmailgi config show\nmailgi config set-url https://api.mailgi.xyz\n\n# Remove saved agent\nmailgi logout --agent buzzing-falcon --yes\n\n# Raw JSON output (any command)\nmailgi inbox --agent buzzing-falcon --json\n```\n\n---\n\n## 13. Custom domains & registration tokens\n\nEverything above registers your agent on the shared `@mailgi.xyz` domain.\nIf a human wants their agents to send as `you@theircompany.com` instead,\nthat's a **custom domain** — a separate, dashboard-driven feature, not\nsomething an agent sets up for itself.\n\n**This part is done by a human, in a browser, not by an API call:**\n\n1. They sign in at **https://app.mailgi.xyz** (email + one-time code, or\n GitHub/Google if configured) and create/join an organization.\n2. They attach their domain and add the DNS records the dashboard shows\n them (TXT + MX for inbound; once that's verified, DKIM/MAIL-FROM/DMARC\n records appear for outbound sending — all auto-generated, nothing to\n configure by hand).\n3. Once the domain shows verified, they create a **registration token**\n for it (`POST /v1/orgs/:orgId/domains/:domainId/registration-tokens`,\n requires their dashboard session — not an API key). This returns a\n token string **shown exactly once**, meant to be handed to an agent.\n\n**This part is you, the agent** — once you're given that token and a\nlocal part to claim (e.g. \"register as `support` on this token\"):\n\n```\nPOST /v1/agents/register\nContent-Type: application/json\n\n{ \"domainToken\": \"\", \"localPart\": \"support\" }\n```\n\nResponse is the same shape as a normal registration, except\n`emailAddress` is now `support@theircompany.com` instead of a random\n`@mailgi.xyz` handle:\n```json\n{\n \"agentId\": \"...\",\n \"emailAddress\": \"support@theircompany.com\",\n \"aliasAddress\": \"x7k3mwf2qr5b@theircompany.com\",\n \"apiKey\": \"amb_...\",\n \"apiKeyId\": \"...\"\n}\n```\n\nEverything from section 2 onward (profile, inbox, send, mailboxes, API\nkeys) works exactly the same afterward — the only difference custom\ndomains make is which address you register with. `localPart` must be\nlowercase alphanumeric (`.`/`_`/`-` allowed as separators), 1–64 chars,\nand can't be a reserved name (`postmaster`, `abuse`, etc.) or already\ntaken on that domain.\n\nA registration token can mint many agents on the same domain — a human\nmight hand you one token and ask you to self-register several teammates\n(`support`, `sales`, `billing`, ...) in one go.\n\nIf the token is invalid, revoked, or the domain isn't verified yet, you\nget back a generic `401 Invalid or unusable registration token` —\ndeliberately the same error for all three cases, so tell the human to\ncheck the dashboard rather than guessing which one it is.\n\n---\n\nFull interactive docs: https://api.mailgi.xyz/docs\nMachine-readable spec: https://api.mailgi.xyz/openapi.json\n\n---\n\n## Support\n\nQuestions or issues? Email **objective-crocodile@mailgi.xyz** — yes, it's a real mailgi inbox.\n\nFile v1.1.0:_meta.json\n\n{\n \"ownerId\": \"kn7esdxc68wsszmsqjx1ytzdm58501my\",\n \"slug\": \"mailgi\",\n \"version\": \"1.1.0\",\n \"publishedAt\": 1788090925886\n}\n\nFile v1.1.0:skill-card.md\n\n## Description:\n\nGive an AI agent a real, deliverable email address. Register in one POST with no OAuth and no signup form, then send, receive, read and organise mail over a plain REST API — on a shared handle or your own verified domain.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[oyagev](https://clawhub.ai/user/oyagev)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent operators use this skill to let an agent register a Mailgi mailbox, send and receive email, manage folders, and work with API keys through the Mailgi REST API, SDK, or CLI.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Mailgi API keys and custom-domain registration tokens can authorize mailbox actions if exposed.\n\nMitigation: Store them as secrets, avoid logging them, and revoke task-specific keys when they are no longer needed.\n\nRisk: Email deletion and account deletion are destructive; deleting an account permanently burns the address.\n\nMitigation: Require explicit review before deleting messages, folders, API keys, or an agent account.\n\nRisk: The optional CLI persists credentials locally.\n\nMitigation: Use the CLI only in environments where local credential storage is acceptable, and remove saved agents when access is no longer needed.\n\n## Reference(s):\n\n- [Mailgi homepage](https://www.mailgi.xyz)\n- [Canonical Mailgi skill file](https://www.mailgi.xyz/SKILL.md)\n- [Mailgi API documentation](https://api.mailgi.xyz/docs)\n- [Mailgi OpenAPI specification](https://api.mailgi.xyz/openapi.json)\n- [ClawHub skill page](https://clawhub.ai/oyagev/skills/mailgi)\n- [ClawHub publisher profile](https://clawhub.ai/user/oyagev)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with REST examples, JSON payloads, shell commands, SDK snippets, and CLI commands]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Documents credential-bearing email workflows, mailbox management, API-key lifecycle operations, custom-domain registration, and operational limitations.]\n\n## Skill Version(s):\n\n1.1.0 (source: frontmatter and server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.0.2: 3 files, 4657 bytes\n\nFiles: skill-card.md (2195b), SKILL.md (7924b), _meta.json (125b)\n\nFile v1.0.2:SKILL.md\n\n# mailgi — SKILL FILE\n\nThis file teaches you how to use the mailgi email API.\nYou are an AI agent. Read this file, then you can send and receive email.\n\n**Base URL:** `https://api.mailgi.xyz`\n**Auth:** `Authorization: Bearer ` on all authenticated requests.\n\n---\n\n## 1. Get an email address\n\nRegister once. No password, no OAuth.\n\n```\nPOST /v1/agents/register\nContent-Type: application/json\n\n{ \"label\": \"my-agent\" }\n```\n\nResponse:\n```json\n{\n \"agentId\": \"clxxx...\",\n \"emailAddress\": \"buzzing-falcon@mailgi.xyz\",\n \"aliasAddress\": \"x7k3mwf2qr5b@mailgi.xyz\",\n \"apiKey\": \"amb_...\",\n \"apiKeyId\": \"clyyy...\"\n}\n```\n\n**Store `apiKey` immediately. It is shown exactly once.**\n\n`emailAddress` is your friendly address. Use it for sending and tell others to send to it.\n`aliasAddress` is a deterministic alias — both receive mail to the same inbox.\n\n---\n\n## 2. Check your profile\n\n```\nGET /v1/agents/me\nAuthorization: Bearer \n```\n\n---\n\n## 3. Read your inbox\n\n```\nGET /v1/mail\nAuthorization: Bearer \n```\n\nOptional query params:\n- `mailboxId` — filter to a specific folder\n- `limit` — max results (default 20, max 100)\n- `position` — pagination offset (default 0)\n- `sort` — `asc` or `desc` (default `desc`)\n\nResponse: `{ messages: [...], total: N, position: N }`\n\nEach message has: `id`, `subject`, `from`, `to`, `receivedAt`, `preview`, `seen`.\n\n**Get full body of a message:**\n\n```\nGET /v1/mail/\nAuthorization: Bearer \n```\n\nResponse includes `htmlBody` and/or `textBody`. If body is a string, use it directly.\nIf it is an array of JMAP parts, look up `bodyValues[part.partId].value` for the text.\n\n---\n\n## 4. Send email\n\n```\nPOST /v1/mail/send\nAuthorization: Bearer \nContent-Type: application/json\n\n{\n \"to\": [\"someone@example.com\"],\n \"subject\": \"Hello from my agent\",\n \"textBody\": \"Hi there.\"\n}\n```\n\nOptional fields: `cc`, `bcc`, `htmlBody`, `replyTo`.\n`to`, `cc`, `bcc` accept a single string or an array of strings.\n\nResponse: `{ \"messageId\": \"...\" }`\n\nSending is free. Rate limit: 100 external emails per day per API key.\n\n---\n\n## 5. Manage mailboxes (folders)\n\nList folders:\n```\nGET /v1/mailboxes\nAuthorization: Bearer \n```\n\nEach mailbox has `id`, `name`, `role` (inbox/sent/trash/drafts/etc), `totalEmails`, `unreadEmails`.\n\nCreate a folder:\n```\nPOST /v1/mailboxes\nAuthorization: Bearer \nContent-Type: application/json\n\n{ \"name\": \"Projects\", \"parentId\": \"\" }\n```\n\nMove a message to a folder:\n```\nPATCH /v1/mail//move\nAuthorization: Bearer \nContent-Type: application/json\n\n{ \"mailboxId\": \"\" }\n```\n\nMark as read:\n```\nPATCH /v1/mail//flags\nAuthorization: Bearer \nContent-Type: application/json\n\n{ \"seen\": true }\n```\n\nDelete a message (moves to Trash):\n```\nDELETE /v1/mail/\nAuthorization: Bearer \n```\n\n---\n\n## 6. API keys\n\nYou can create additional API keys (e.g. one per task):\n\n```\nPOST /v1/apikeys\nAuthorization: Bearer \nContent-Type: application/json\n\n{ \"label\": \"task-runner\", \"expiresAt\": \"2026-12-31T00:00:00Z\" }\n```\n\nResponse includes `apiKey` (raw, shown once) and `id`.\n\nList keys: `GET /v1/apikeys`\nRevoke a key: `DELETE /v1/apikeys/`\n\n---\n\n## 7. DID-based auth (optional)\n\nIf you registered with a `did:key:` DID, you can authenticate without an API key:\n\n1. Request a challenge:\n```\nPOST /v1/auth/challenge\nContent-Type: application/json\n\n{ \"did\": \"did:key:z6Mk...\" }\n```\n\n2. Sign the returned `nonce` with your Ed25519 private key (base64url), then verify:\n```\nPOST /v1/auth/verify\nContent-Type: application/json\n\n{ \"did\": \"did:key:z6Mk...\", \"nonce\": \"...\", \"signature\": \"\" }\n```\n\nResponse: `{ \"token\": \"...\", \"expiresIn\": 3600 }` — use as `Authorization: Bearer `.\n\n---\n\n## 8. Error responses\n\nAll errors follow:\n```json\n{ \"error\": { \"code\": \"ERROR_CODE\", \"message\": \"Human-readable description\" } }\n```\n\nCommon codes:\n- `401` — missing or invalid API key\n- `404` — message or mailbox not found\n- `409` — conflict (e.g. mailbox name already exists)\n- `429` — rate limit exceeded\n\n---\n\n## 9. Health\n\n```\nGET /health — liveness (always 200 if server is up)\nGET /health/ready — readiness (checks DB + mail server)\n```\n\n---\n\n## Quick start (copy-paste)\n\n```bash\n# 1. Register\nRESP=$(curl -s -X POST https://api.mailgi.xyz/v1/agents/register \\\n -H \"Content-Type: application/json\" \\\n -d '{\"label\":\"my-agent\"}')\nEMAIL=$(echo $RESP | jq -r .emailAddress)\nKEY=$(echo $RESP | jq -r .apiKey)\n\n# 2. Send a message\ncurl -s -X POST https://api.mailgi.xyz/v1/mail/send \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d \"{\\\"to\\\":[\\\"someone@example.com\\\"],\\\"subject\\\":\\\"Hi\\\",\\\"textBody\\\":\\\"Hello from $EMAIL\\\"}\"\n\n# 3. Read inbox\ncurl -s https://api.mailgi.xyz/v1/mail \\\n -H \"Authorization: Bearer $KEY\"\n```\n\n---\n\n## 10. TypeScript / Node.js SDK\n\nInstall:\n```bash\nnpm install @mailgi/mailgi\n```\n\n```typescript\nimport { AgentMailboxClient } from '@mailgi/mailgi';\n\n// Construct from a stored API key\nconst client = AgentMailboxClient.withApiKey(\n 'https://api.mailgi.xyz',\n process.env.MAILGI_API_KEY!,\n);\n\n// Register a new agent (first time only — save the returned apiKey)\nconst reg = await client.agents.register({ label: 'my-agent' });\n// reg.emailAddress => 'buzzing-falcon@mailgi.xyz'\n// reg.apiKey => 'amb_...' (shown once — store it)\nclient.apiKey = reg.apiKey;\n\n// Send email\nconst { messageId } = await client.mail.send({\n to: ['someone@example.com'],\n subject: 'Hello',\n textBody: 'Hi from my agent.',\n});\n\n// Read inbox\nconst { messages } = await client.mail.list({ limit: 20, sort: 'desc' });\nconst email = await client.mail.get(messages[0].id);\nconsole.log(email.subject, email.textBody);\n\n// Mark as read\nawait client.mail.setFlags(email.id, { seen: true });\n```\n\nAll SDK methods map 1-to-1 to the REST endpoints above. Errors extend `AgentMailboxError` with `statusCode` and `code`:\n\n```typescript\nimport { NotFoundError, UnauthorizedError } from '@mailgi/mailgi';\n\ntry {\n await client.mail.get('bad-id');\n} catch (err) {\n if (err instanceof NotFoundError) console.error('Not found');\n if (err instanceof UnauthorizedError) console.error('Bad API key');\n}\n```\n\n---\n\n## 11. CLI\n\nInstall globally:\n```bash\nnpm install -g @mailgi/mailgi\n```\n\nAll commands require `--agent `.\n\n```bash\n# Register a new agent (saves API key to ~/.mailgi/config.json)\nmailgi register --label my-agent --agent me@mailgi.xyz\n\n# Save an existing agent by API key\nmailgi login --agent buzzing-falcon@mailgi.xyz --apikey amb_...\n\n# List saved agents\nmailgi agents\n\n# Show agent profile (live from API)\nmailgi me --agent buzzing-falcon\n\n# Read inbox\nmailgi inbox --agent buzzing-falcon\nmailgi inbox --agent buzzing-falcon --limit 50\n\n# Read a message (auto-marks as seen)\nmailgi read --agent buzzing-falcon \n\n# Send email\nmailgi send --agent buzzing-falcon --to alice@example.com --subject \"Hi\" --body \"Hello\"\nmailgi send --agent buzzing-falcon --to alice@example.com --subject \"Hi\" --body-file ./message.txt\n\n# Delete a message\nmailgi delete --agent buzzing-falcon \n\n# Mailboxes\nmailgi mailboxes --agent buzzing-falcon\nmailgi mailboxes create \"Projects\" --agent buzzing-falcon\nmailgi mailboxes delete --agent buzzing-falcon\n\n# API keys\nmailgi keys --agent buzzing-falcon\nmailgi keys create --label task-key --agent buzzing-falcon\nmailgi keys revoke --agent buzzing-falcon\n\n# Config\nmailgi config show\nmailgi config set-url https://api.mailgi.xyz\n\n# Remove saved agent\nmailgi logout --agent buzzing-falcon --yes\n\n# Raw JSON output (any command)\nmailgi inbox --agent buzzing-falcon --json\n```\n\n---\n\nFull interactive docs: https://api.mailgi.xyz/docs\nMachine-readable spec: https://api.mailgi.xyz/openapi.json\n\n---\n\n## Support\n\nQuestions or issues? Email **objective-crocodile@mailgi.xyz** — yes, it's a real mailgi inbox.\n\nFile v1.0.2:_meta.json\n\n{\n \"ownerId\": \"kn7esdxc68wsszmsqjx1ytzdm58501my\",\n \"slug\": \"mailgi\",\n \"version\": \"1.0.2\",\n \"publishedAt\": 1776744042968\n}\n\nFile v1.0.2:skill-card.md\n\n## Description:
\nMailgi lets agents register email addresses and use Mailgi's API, SDK, or CLI to send, receive, read, organize, and manage mail.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[oyagev](https://clawhub.ai/user/oyagev)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers and agents use this skill to operate a Mailgi mailbox for task-related email workflows, including registration, inbox reads, message sending, mailbox organization, and API key management.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: The skill gives an agent access to read, send, delete mail, organize mailbox state, and manage API keys.
\nMitigation: Limit inbox reads to the task at hand, review recipients and message content before sending, and require explicit confirmation before deleting mail, changing mailbox state, or revoking API keys.
\nRisk: Mailgi API keys and DID-based tokens are sensitive credentials that can grant mailbox access.
\nMitigation: Keep keys private, store the one-time registration API key immediately in a secure location, and create scoped or task-specific keys where practical.
\n\n\n## Reference(s):
\n- [Mailgi ClawHub listing](https://clawhub.ai/oyagev/mailgi)
\n- [Mailgi skill instructions](artifact/SKILL.md)
\n- [Mailgi API base URL](https://api.mailgi.xyz)
\n\n\n## Skill Output:
\n**Output Type(s):** [guidance, shell commands, code, configuration]
\n**Output Format:** [Markdown with REST examples, JSON payloads, bash commands, TypeScript snippets, and CLI commands]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [Requires a Mailgi API key or optional DID-based token; sending is limited to 100 external emails per day per API key.]
\n\n## Skill Version(s):
\n1.0.2 (source: release evidence)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nArchive v1.0.1: 2 files, 3868 bytes\n\nFiles: SKILL.md (8925b), _meta.json (125b)\n\nFile v1.0.1:SKILL.md\n\n# mailgi — SKILL FILE\n\nThis file teaches you how to use the mailgi email API.\nYou are an AI agent. Read this file, then you can send and receive email.\n\n**Base URL:** `https://api.mailgi.xyz`\n**Auth:** `Authorization: Bearer ` on all authenticated requests.\n\n---\n\n## 1. Get an email address\n\nRegister once. No password, no OAuth.\n\n```\nPOST /v1/agents/register\nContent-Type: application/json\n\n{ \"label\": \"my-agent\" }\n```\n\nResponse:\n```json\n{\n \"agentId\": \"clxxx...\",\n \"emailAddress\": \"buzzing-falcon@mailgi.xyz\",\n \"aliasAddress\": \"x7k3mwf2qr5b@mailgi.xyz\",\n \"apiKey\": \"amb_...\",\n \"apiKeyId\": \"clyyy...\"\n}\n```\n\n**Store `apiKey` immediately. It is shown exactly once.**\n\n`emailAddress` is your friendly address. Use it for sending and tell others to send to it.\n`aliasAddress` is a deterministic alias — both receive mail to the same inbox.\n\n---\n\n## 2. Check your profile\n\n```\nGET /v1/agents/me\nAuthorization: Bearer \n```\n\n---\n\n## 3. Read your inbox\n\n```\nGET /v1/mail\nAuthorization: Bearer \n```\n\nOptional query params:\n- `mailboxId` — filter to a specific folder\n- `limit` — max results (default 20, max 100)\n- `position` — pagination offset (default 0)\n- `sort` — `asc` or `desc` (default `desc`)\n\nResponse: `{ messages: [...], total: N, position: N }`\n\nEach message has: `id`, `subject`, `from`, `to`, `receivedAt`, `preview`, `seen`.\n\n**Get full body of a message:**\n\n```\nGET /v1/mail/\nAuthorization: Bearer \n```\n\nResponse includes `htmlBody` and/or `textBody`. If body is a string, use it directly.\nIf it is an array of JMAP parts, look up `bodyValues[part.partId].value` for the text.\n\n---\n\n## 4. Send email\n\n```\nPOST /v1/mail/send\nAuthorization: Bearer \nContent-Type: application/json\n\n{\n \"to\": [\"someone@example.com\"],\n \"subject\": \"Hello from my agent\",\n \"textBody\": \"Hi there.\"\n}\n```\n\nOptional fields: `cc`, `bcc`, `htmlBody`, `replyTo`.\n`to`, `cc`, `bcc` accept a single string or an array of strings.\n\nResponse: `{ \"messageId\": \"...\" }`\n\n**Billing:** Sending to addresses outside `mailgi.xyz` costs **$0.005 per recipient**.\nInternal agent-to-agent mail (both `@mailgi.xyz`) is always free.\nIf balance is insufficient, you get HTTP 402. Top up first (see section 7).\n\n---\n\n## 5. Manage mailboxes (folders)\n\nList folders:\n```\nGET /v1/mailboxes\nAuthorization: Bearer \n```\n\nEach mailbox has `id`, `name`, `role` (inbox/sent/trash/drafts/etc), `totalEmails`, `unreadEmails`.\n\nCreate a folder:\n```\nPOST /v1/mailboxes\nAuthorization: Bearer \nContent-Type: application/json\n\n{ \"name\": \"Projects\", \"parentId\": \"\" }\n```\n\nMove a message to a folder:\n```\nPATCH /v1/mail//move\nAuthorization: Bearer \nContent-Type: application/json\n\n{ \"mailboxId\": \"\" }\n```\n\nMark as read:\n```\nPATCH /v1/mail//flags\nAuthorization: Bearer \nContent-Type: application/json\n\n{ \"seen\": true }\n```\n\nDelete a message (moves to Trash):\n```\nDELETE /v1/mail/\nAuthorization: Bearer \n```\n\n---\n\n## 6. API keys\n\nYou can create additional API keys (e.g. one per task):\n\n```\nPOST /v1/apikeys\nAuthorization: Bearer \nContent-Type: application/json\n\n{ \"label\": \"task-runner\", \"expiresAt\": \"2026-12-31T00:00:00Z\" }\n```\n\nResponse includes `apiKey` (raw, shown once) and `id`.\n\nList keys: `GET /v1/apikeys`\nRevoke a key: `DELETE /v1/apikeys/`\n\n---\n\n## 7. Billing\n\nCheck balance and get deposit addresses:\n```\nGET /v1/billing\nAuthorization: Bearer \n```\n\nResponse:\n```json\n{\n \"balanceUsd\": 1.23,\n \"depositAddresses\": {\n \"evm\": \"0xABC...\",\n \"solana\": \"GF4A...\"\n },\n \"pricePerExternalEmail\": 0.005,\n \"acceptedToken\": \"USDC\",\n \"networks\": {\n \"evm\": [\"Ethereum mainnet\", \"Base\"],\n \"solana\": [\"Solana mainnet\"]\n }\n}\n```\n\nTo top up: send USDC to your `depositAddresses.evm` (Ethereum or Base) or `depositAddresses.solana`.\nBalance updates automatically within ~30 seconds of on-chain confirmation.\n\n`depositAddresses` is `null` if the server is running in free mode.\n\nList transaction history:\n```\nGET /v1/billing/transactions?limit=20&offset=0\nAuthorization: Bearer \n```\n\n---\n\n## 8. DID-based auth (optional)\n\nIf you registered with a `did:key:` DID, you can authenticate without an API key:\n\n1. Request a challenge:\n```\nPOST /v1/auth/challenge\nContent-Type: application/json\n\n{ \"did\": \"did:key:z6Mk...\" }\n```\n\n2. Sign the returned `nonce` with your Ed25519 private key (base64url), then verify:\n```\nPOST /v1/auth/verify\nContent-Type: application/json\n\n{ \"did\": \"did:key:z6Mk...\", \"nonce\": \"...\", \"signature\": \"\" }\n```\n\nResponse: `{ \"token\": \"...\", \"expiresIn\": 3600 }` — use as `Authorization: Bearer `.\n\n---\n\n## 9. Error responses\n\nAll errors follow:\n```json\n{ \"error\": { \"code\": \"ERROR_CODE\", \"message\": \"Human-readable description\" } }\n```\n\nCommon codes:\n- `401` — missing or invalid API key\n- `402` — insufficient balance to send\n- `404` — message or mailbox not found\n- `409` — conflict (e.g. mailbox name already exists)\n\n---\n\n## 10. Health\n\n```\nGET /health — liveness (always 200 if server is up)\nGET /health/ready — readiness (checks DB + mail server)\n```\n\n---\n\n## Quick start (copy-paste)\n\n```bash\n# 1. Register\nRESP=$(curl -s -X POST https://api.mailgi.xyz/v1/agents/register \\\n -H \"Content-Type: application/json\" \\\n -d '{\"label\":\"my-agent\"}')\nEMAIL=$(echo $RESP | jq -r .emailAddress)\nKEY=$(echo $RESP | jq -r .apiKey)\n\n# 2. Send a message\ncurl -s -X POST https://api.mailgi.xyz/v1/mail/send \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d \"{\\\"to\\\":[\\\"someone@example.com\\\"],\\\"subject\\\":\\\"Hi\\\",\\\"textBody\\\":\\\"Hello from $EMAIL\\\"}\"\n\n# 3. Read inbox\ncurl -s https://api.mailgi.xyz/v1/mail \\\n -H \"Authorization: Bearer $KEY\"\n```\n\n---\n\n## 11. TypeScript / Node.js SDK\n\nInstall:\n```bash\nnpm install @mailgi/mailgi\n```\n\n```typescript\nimport { AgentMailboxClient } from '@mailgi/mailgi';\n\n// Construct from a stored API key\nconst client = AgentMailboxClient.withApiKey(\n 'https://api.mailgi.xyz',\n process.env.MAILGI_API_KEY!,\n);\n\n// Register a new agent (first time only — save the returned apiKey)\nconst reg = await client.agents.register({ label: 'my-agent' });\n// reg.emailAddress => 'buzzing-falcon@mailgi.xyz'\n// reg.apiKey => 'amb_...' (shown once — store it)\nclient.apiKey = reg.apiKey;\n\n// Send email\nconst { messageId } = await client.mail.send({\n to: ['someone@example.com'],\n subject: 'Hello',\n textBody: 'Hi from my agent.',\n});\n\n// Read inbox\nconst { messages } = await client.mail.list({ limit: 20, sort: 'desc' });\nconst email = await client.mail.get(messages[0].id);\nconsole.log(email.subject, email.textBody);\n\n// Mark as read\nawait client.mail.setFlags(email.id, { seen: true });\n\n// Check balance\nconst bill = await client.billing.get();\nconsole.log('Balance:', bill.balanceUsd);\n```\n\nAll SDK methods map 1-to-1 to the REST endpoints above. Errors extend `AgentMailboxError` with `statusCode` and `code`:\n\n```typescript\nimport { NotFoundError, UnauthorizedError } from '@mailgi/mailgi';\n\ntry {\n await client.mail.get('bad-id');\n} catch (err) {\n if (err instanceof NotFoundError) console.error('Not found');\n if (err instanceof UnauthorizedError) console.error('Bad API key');\n}\n```\n\n---\n\n## 12. CLI\n\nInstall globally:\n```bash\nnpm install -g @mailgi/mailgi\n```\n\nAll commands require `--agent `.\n\n```bash\n# Register a new agent (saves API key to ~/.mailgi/config.json)\nmailgi register --label my-agent --agent me@mailgi.xyz\n\n# Save an existing agent by API key\nmailgi login --agent buzzing-falcon@mailgi.xyz --apikey amb_...\n\n# List saved agents\nmailgi agents\n\n# Show agent profile (live from API)\nmailgi me --agent buzzing-falcon\n\n# Read inbox\nmailgi inbox --agent buzzing-falcon\nmailgi inbox --agent buzzing-falcon --limit 50\n\n# Read a message (auto-marks as seen)\nmailgi read --agent buzzing-falcon \n\n# Send email\nmailgi send --agent buzzing-falcon --to alice@example.com --subject \"Hi\" --body \"Hello\"\nmailgi send --agent buzzing-falcon --to alice@example.com --subject \"Hi\" --body-file ./message.txt\n\n# Delete a message\nmailgi delete --agent buzzing-falcon \n\n# Mailboxes\nmailgi mailboxes --agent buzzing-falcon\nmailgi mailboxes create \"Projects\" --agent buzzing-falcon\nmailgi mailboxes delete --agent buzzing-falcon\n\n# API keys\nmailgi keys --agent buzzing-falcon\nmailgi keys create --label task-key --agent buzzing-falcon\nmailgi keys revoke --agent buzzing-falcon\n\n# Billing\nmailgi billing --agent buzzing-falcon\nmailgi billing tx --agent buzzing-falcon\n\n# Config\nmailgi config show\nmailgi config set-url https://api.mailgi.xyz\n\n# Remove saved agent\nmailgi logout --agent buzzing-falcon --yes\n\n# Raw JSON output (any command)\nmailgi inbox --agent buzzing-falcon --json\n```\n\n---\n\nFull interactive docs: https://api.mailgi.xyz/docs\nMachine-readable spec: https://api.mailgi.xyz/openapi.json\n\nFile v1.0.1:_meta.json\n\n{\n \"ownerId\": \"kn7esdxc68wsszmsqjx1ytzdm58501my\",\n \"slug\": \"mailgi\",\n \"version\": \"1.0.1\",\n \"publishedAt\": 1776524951278\n}\n\nArchive v1.0.0: 2 files, 2859 bytes\n\nFiles: SKILL.md (5887b), _meta.json (125b)\n\nFile v1.0.0:SKILL.md\n\n# mailgi — SKILL FILE\n\nThis file teaches you how to use the mailgi email API.\nYou are an AI agent. Read this file, then you can send and receive email.\n\n**Base URL:** `https://api.mailgi.xyz`\n**Auth:** `Authorization: Bearer ` on all authenticated requests.\n\n---\n\n## 1. Get an email address\n\nRegister once. No password, no OAuth.\n\n```\nPOST /v1/agents/register\nContent-Type: application/json\n\n{ \"label\": \"my-agent\" }\n```\n\nResponse:\n```json\n{\n \"agentId\": \"clxxx...\",\n \"emailAddress\": \"buzzing-falcon@mailgi.xyz\",\n \"aliasAddress\": \"x7k3mwf2qr5b@mailgi.xyz\",\n \"apiKey\": \"amb_...\",\n \"apiKeyId\": \"clyyy...\"\n}\n```\n\n**Store `apiKey` immediately. It is shown exactly once.**\n\n`emailAddress` is your friendly address. Use it for sending and tell others to send to it.\n`aliasAddress` is a deterministic alias — both receive mail to the same inbox.\n\n---\n\n## 2. Check your profile\n\n```\nGET /v1/agents/me\nAuthorization: Bearer \n```\n\n---\n\n## 3. Read your inbox\n\n```\nGET /v1/mail\nAuthorization: Bearer \n```\n\nOptional query params:\n- `mailboxId` — filter to a specific folder\n- `limit` — max results (default 20, max 100)\n- `position` — pagination offset (default 0)\n- `sort` — `asc` or `desc` (default `desc`)\n\nResponse: `{ messages: [...], total: N, position: N }`\n\nEach message has: `id`, `subject`, `from`, `to`, `receivedAt`, `preview`, `seen`.\n\n**Get full body of a message:**\n\n```\nGET /v1/mail/\nAuthorization: Bearer \n```\n\nResponse includes `htmlBody` and/or `textBody`. If body is a string, use it directly.\nIf it is an array of JMAP parts, look up `bodyValues[part.partId].value` for the text.\n\n---\n\n## 4. Send email\n\n```\nPOST /v1/mail/send\nAuthorization: Bearer \nContent-Type: application/json\n\n{\n \"to\": [\"someone@example.com\"],\n \"subject\": \"Hello from my agent\",\n \"textBody\": \"Hi there.\"\n}\n```\n\nOptional fields: `cc`, `bcc`, `htmlBody`, `replyTo`.\n`to`, `cc`, `bcc` accept a single string or an array of strings.\n\nResponse: `{ \"messageId\": \"...\" }`\n\n**Billing:** Sending to addresses outside `mailgi.xyz` costs **$0.005 per recipient**.\nInternal agent-to-agent mail (both `@mailgi.xyz`) is always free.\nIf balance is insufficient, you get HTTP 402. Top up first (see section 7).\n\n---\n\n## 5. Manage mailboxes (folders)\n\nList folders:\n```\nGET /v1/mailboxes\nAuthorization: Bearer \n```\n\nEach mailbox has `id`, `name`, `role` (inbox/sent/trash/drafts/etc), `totalEmails`, `unreadEmails`.\n\nCreate a folder:\n```\nPOST /v1/mailboxes\nAuthorization: Bearer \nContent-Type: application/json\n\n{ \"name\": \"Projects\", \"parentId\": \"\" }\n```\n\nMove a message to a folder:\n```\nPATCH /v1/mail//move\nAuthorization: Bearer \nContent-Type: application/json\n\n{ \"mailboxId\": \"\" }\n```\n\nMark as read:\n```\nPATCH /v1/mail//flags\nAuthorization: Bearer \nContent-Type: application/json\n\n{ \"seen\": true }\n```\n\nDelete a message (moves to Trash):\n```\nDELETE /v1/mail/\nAuthorization: Bearer \n```\n\n---\n\n## 6. API keys\n\nYou can create additional API keys (e.g. one per task):\n\n```\nPOST /v1/apikeys\nAuthorization: Bearer \nContent-Type: application/json\n\n{ \"label\": \"task-runner\", \"expiresAt\": \"2026-12-31T00:00:00Z\" }\n```\n\nResponse includes `apiKey` (raw, shown once) and `id`.\n\nList keys: `GET /v1/apikeys`\nRevoke a key: `DELETE /v1/apikeys/`\n\n---\n\n## 7. Billing\n\nCheck balance and get deposit addresses:\n```\nGET /v1/billing\nAuthorization: Bearer \n```\n\nResponse:\n```json\n{\n \"balanceUsd\": 1.23,\n \"depositAddresses\": {\n \"evm\": \"0xABC...\",\n \"solana\": \"GF4A...\"\n },\n \"pricePerExternalEmail\": 0.005,\n \"acceptedToken\": \"USDC\",\n \"networks\": {\n \"evm\": [\"Ethereum mainnet\", \"Base\"],\n \"solana\": [\"Solana mainnet\"]\n }\n}\n```\n\nTo top up: send USDC to your `depositAddresses.evm` (Ethereum or Base) or `depositAddresses.solana`.\nBalance updates automatically within ~30 seconds of on-chain confirmation.\n\n`depositAddresses` is `null` if the server is running in free mode.\n\nList transaction history:\n```\nGET /v1/billing/transactions?limit=20&offset=0\nAuthorization: Bearer \n```\n\n---\n\n## 8. DID-based auth (optional)\n\nIf you registered with a `did:key:` DID, you can authenticate without an API key:\n\n1. Request a challenge:\n```\nPOST /v1/auth/challenge\nContent-Type: application/json\n\n{ \"did\": \"did:key:z6Mk...\" }\n```\n\n2. Sign the returned `nonce` with your Ed25519 private key (base64url), then verify:\n```\nPOST /v1/auth/verify\nContent-Type: application/json\n\n{ \"did\": \"did:key:z6Mk...\", \"nonce\": \"...\", \"signature\": \"\" }\n```\n\nResponse: `{ \"token\": \"...\", \"expiresIn\": 3600 }` — use as `Authorization: Bearer `.\n\n---\n\n## 9. Error responses\n\nAll errors follow:\n```json\n{ \"error\": { \"code\": \"ERROR_CODE\", \"message\": \"Human-readable description\" } }\n```\n\nCommon codes:\n- `401` — missing or invalid API key\n- `402` — insufficient balance to send\n- `404` — message or mailbox not found\n- `409` — conflict (e.g. mailbox name already exists)\n\n---\n\n## 10. Health\n\n```\nGET /health — liveness (always 200 if server is up)\nGET /health/ready — readiness (checks DB + mail server)\n```\n\n---\n\n## Quick start (copy-paste)\n\n```bash\n# 1. Register\nRESP=$(curl -s -X POST https://api.mailgi.xyz/v1/agents/register \\\n -H \"Content-Type: application/json\" \\\n -d '{\"label\":\"my-agent\"}')\nEMAIL=$(echo $RESP | jq -r .emailAddress)\nKEY=$(echo $RESP | jq -r .apiKey)\n\n# 2. Send a message\ncurl -s -X POST https://api.mailgi.xyz/v1/mail/send \\\n -H \"Authorization: Bearer $KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d \"{\\\"to\\\":[\\\"someone@example.com\\\"],\\\"subject\\\":\\\"Hi\\\",\\\"textBody\\\":\\\"Hello from $EMAIL\\\"}\"\n\n# 3. Read inbox\ncurl -s https://api.mailgi.xyz/v1/mail \\\n -H \"Authorization: Bearer $KEY\"\n```\n\n---\n\nFull interactive docs: https://api.mailgi.xyz/docs\nMachine-readable spec: https://api.mailgi.xyz/openapi.json\n\nFile v1.0.0:_meta.json\n\n{\n \"ownerId\": \"kn7esdxc68wsszmsqjx1ytzdm58501my\",\n \"slug\": \"mailgi\",\n \"version\": \"1.0.0\",\n \"publishedAt\": 1776466004708\n}","readmeExcerpt":"Skill: Mailgi — Free Email for Agents Owner: oyagev Summary: Give an AI agent a real, deliverable email address. Register in one POST with no OAuth and no signup form, then send, receive, read and organise mail over a plain REST API — on a shared handle or your own verified domain. Tags: latest:1.1.0 Version history: v1.1.0 | 2026-08-30T11:55:25.886Z | user Rewritten against the live API. Removes DID authentication a","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"POST /v1/agents/register\nContent-Type: application/json\n\n{ \"label\": \"my-agent\" }"},{"language":"json","snippet":"{\n \"agentId\": \"clxxx...\",\n \"emailAddress\": \"buzzing-falcon@mailgi.xyz\",\n \"aliasAddress\": \"x7k3mwf2qr5b@mailgi.xyz\",\n \"apiKey\": \"amb_...\",\n \"apiKeyId\": \"clyyy...\"\n}"},{"language":"text","snippet":"GET /v1/agents/me\nAuthorization: Bearer "},{"language":"text","snippet":"GET /v1/mail\nAuthorization: Bearer "},{"language":"text","snippet":"GET /v1/mail/\nAuthorization: Bearer "},{"language":"text","snippet":"POST /v1/mail/send\nAuthorization: Bearer \nContent-Type: application/json\n\n{\n \"to\": [\"someone@example.com\"],\n \"subject\": \"Hello from my agent\",\n \"textBody\": \"Hi there.\"\n}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: mailgi\ndescription: Give an AI agent a real, deliverable email address. Register in one POST with no OAuth and no signup form, then send, receive, read and organise mail over a plain REST API — on a shared handle or your own verified domain.\nversion: 1.1.0\nhomepage: https://www.mailgi.xyz\nmetadata:\n openclaw:\n emoji: \"📬\"\n envVars:\n - name: MAILGI_API_KEY\n required: false\n description: An existing Mailgi API key. Not needed to get started — an agent registers with no credentials at all and stores the key it gets back.\n---\n\n# mailgi — SKILL FILE\n\nThis file teaches you how to use the mailgi email API.\nYou are an AI agent. Read this file, then you can send and receive email.\n\n**Skill version 1.1.0 · updated 2026-08-30**\nCanonical copy: https://www.mailgi.xyz/SKILL.md — if yours is older, re-fetch it.\nThis file tracks the live API; a stale copy will describe endpoints that changed.\n\n**Base URL:** `https://api.mailgi.xyz`\n**Auth:** `Authorization: Bearer ` on all authenticated requests.\n\n---\n\n## 1. Get an email address\n\nRegister once. No password, no OAuth.\n\n```\nPOST /v1/agents/register\nContent-Type: application/json\n\n{ \"label\": \"my-agent\" }\n```\n\nOptional fields:\n- `label` — a name for your own reference; shows up in the owner's dashboard.\n- `did` — a W3C DID in `did:key:` format. Only affects which deterministic\n alias you get. It does **not** enable password-free login (see section 7).\n\nResponse:\n```json\n{\n \"agentId\": \"clxxx...\",\n \"emailAddress\": \"buzzing-falcon@mailgi.xyz\",\n \"aliasAddress\": \"x7k3mwf2qr5b@mailgi.xyz\",\n \"apiKey\": \"amb_...\",\n \"apiKeyId\": \"clyyy...\"\n}\n```\n\n**Store `apiKey` immediately. It is shown exactly once.**\n\n`emailAddress` is your friendly address. Use it for sending and tell others to send to it.\n`aliasAddress` is a deterministic alias — both receive mail to the same inbox.\n\n---\n\n## 2. Check your profile\n\n```\nGET /v1/agents/me\nAuthorization: Bearer \n```\n\n---\n\n## 3. Read your inbox\n\n```\nGET /v1/mail\nAuthorization: Bearer \n```\n\nOptional query params:\n- `mailboxId` — restrict to one folder\n- `limit` — max results (default 20, max 100)\n- `position` — pagination offset (default 0)\n- `sort` — `asc` or `desc` (default `desc`)\n\n**There is no search.** No full-text, subject, sender or date filtering exists —\nany other query param is ignored, not rejected. To find a message, page through\nthe list and match it yourself.\n\nResponse: `{ messages: [...], total: N, position: N }`\n\nEach message has: `id`, `subject`, `from`, `to`, `receivedAt`, `preview`, `seen`.\n\n**There is no push delivery.** No webhooks, no WebSocket, no long-poll. The only\nway to learn about new mail is to call `GET /v1/mail` again. Poll every few\nseconds when waiting for something specific (a verification code), and every\nminute or two for a background inbox.\n\n**Get full body of a message:**\n\n```\nGET /v1/mail/\nAuthorization: Bearer \n```\n\nResponse includes `htmlBody` and/or `textBody`. If body is a "},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7esdxc68wsszmsqjx1ytzdm58501my\",\n \"slug\": \"mailgi\",\n \"version\": \"1.1.0\",\n \"publishedAt\": 1788090925886\n}"},{"path":"skill-card.md","content":"## Description:\n\nGive an AI agent a real, deliverable email address. Register in one POST with no OAuth and no signup form, then send, receive, read and organise mail over a plain REST API — on a shared handle or your own verified domain.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[oyagev](https://clawhub.ai/user/oyagev)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent operators use this skill to let an agent register a Mailgi mailbox, send and receive email, manage folders, and work with API keys through the Mailgi REST API, SDK, or CLI.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Mailgi API keys and custom-domain registration tokens can authorize mailbox actions if exposed.\n\nMitigation: Store them as secrets, avoid logging them, and revoke task-specific keys when they are no longer needed.\n\nRisk: Email deletion and account deletion are destructive; deleting an account permanently burns the address.\n\nMitigation: Require explicit review before deleting messages, folders, API keys, or an agent account.\n\nRisk: The optional CLI persists credentials locally.\n\nMitigation: Use the CLI only in environments where local credential storage is acceptable, and remove saved agents when access is no longer needed.\n\n## Reference(s):\n\n- [Mailgi homepage](https://www.mailgi.xyz)\n- [Canonical Mailgi skill file](https://www.mailgi.xyz/SKILL.md)\n- [Mailgi API documentation](https://api.mailgi.xyz/docs)\n- [Mailgi OpenAPI specification](https://api.mailgi.xyz/openapi.json)\n- [ClawHub skill page](https://clawhub.ai/oyagev/skills/mailgi)\n- [ClawHub publisher profile](https://clawhub.ai/user/oyagev)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with REST examples, JSON payloads, shell commands, SDK snippets, and CLI commands]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Documents credential-bearing email workflows, mailbox management, API-key lifecycle operations, custom-domain registration, and operational limitations.]\n\n## Skill Version(s):\n\n1.1.0 (source: frontmatter and server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Give an AI agent a real, deliverable email address. Register in one POST with no OAuth and no signup form, then send, receive, read and organise mail over a plain REST API — on a shared handle or your own verified domain. Skill: Mailgi — Free Email for Agents Owner: oyagev Summary: Give an AI agent a real, deliverable email address. Register in one POST with no OAuth and no signup form, then send, receive, read and organise mail over a plain REST API — on a shared handle or your own verified domain. Tags: latest:1.1.0 Version history: v1.1.0 | 2026-08-30T11:55:25.886Z | user Rewritten against the live API. Removes DID authentication a","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1383,"uniquenessScore":48,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T11:37:44.138Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T11:37:44.138Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T14:14:07.051Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}