{"uid":"cap_pncavHkYkIMCtFMN3jJl8","slug":"inbox-withzero-xyz-publish-event-to-inbox-dbe41c17","name":"Publish Event to Inbox","description":"Publish an event into your inbox. 📖 Full guide: https://inbox.withzero.xyz/llms.txt","url":"https://inbox.withzero.xyz/api/v1/events","method":"POST","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["topic","payload"],"properties":{"topic":{"type":"string","maxLength":256,"minLength":1,"description":"Dot-delimited topic, e.g. \"render.completed\"."},"payload":{"description":"Arbitrary JSON event body."},"attributes":{"type":"object","description":"Optional flat metadata.","propertyNames":{"type":"string"},"additionalProperties":{}},"idempotencyKey":{"type":"string","maxLength":256,"description":"Repeated key for the same recipient is a no-op."}},"additionalProperties":false},"responseSchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["deliveries"],"properties":{"deliveries":{"type":"array","items":{"type":"object","required":["owner","id","status"],"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Stored message id (existing id when duplicate)."},"owner":{"type":"string","description":"Recipient inbox wallet."},"status":{"enum":["delivered","duplicate","skipped_no_lease","skipped_full"],"type":"string"}},"additionalProperties":false},"description":"One entry per recipient: the publisher itself plus any subscribers."}},"additionalProperties":false},"example":{"request":{"topic":"test.event.published","payload":{"message":"QA test event","eventType":"test","timestamp":"2024-01-15T10:30:00Z"},"attributes":{"source":"qa-agent","environment":"test"},"idempotencyKey":"zero-qa@agentmail.to"},"response":{"deliveries":[{"id":"c1b0e17b-ecb1-4f55-902d-ece603aaf5e8","owner":"0x9cc42f3d9245b867acccd630b43f906c1665b176","status":"delivered"}]}},"exampleRequest":{"topic":"test.event.published","payload":{"message":"QA test event","eventType":"test","timestamp":"2024-01-15T10:30:00Z"},"attributes":{"source":"qa-agent","environment":"test"},"idempotencyKey":"zero-qa@agentmail.to"},"tags":[],"displayCostAmount":"0","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"proven_free","priceSource":"registry","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"metered","summary":"metered — billed by usage","primary":{"kind":"metered","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"},"accepted":[{"kind":"metered","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"}]},"paymentMethods":[{"uid":"pm_OTackUQOvrV1Qigq8LEDW","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0","costPer":"request","priority":0,"asset":"0x20C000000000000000000000b9537d11c60E8b50","unit":"request","depositMicros":null,"planRef":"inbox.publish:1"}],"brandName":"inbox.withzero.xyz","brandSlug":"inbox-withzero-xyz-mpp","brandBaseUrl":"https://inbox.withzero.xyz","brandDocsUrl":null,"whatItDoes":"Publishes a named event with an arbitrary JSON payload into the caller's inbox, fanning out to any subscribers","exampleAgentPrompt":"Publish a 'render.completed' event to my inbox with a payload of {jobId: 'abc123', status: 'done'} — use idempotency key 'render-abc123' so it won't be duplicated if retried.","exampleUseCases":[{"title":"Coordinate async image generation","prompt":"When the image generation finishes, publish a 'image.ready' event to my inbox with the image URL and metadata — make sure to use an idempotency key so duplicate calls don't create multiple events."},{"title":"Notify subscribers of data sync","prompt":"After syncing the customer database, emit a 'sync.completed' event with the record count and timestamp so any downstream agents know the data is fresh and can act on it."},{"title":"Trigger workflow stage transitions","prompt":"Once the approval is granted, publish a 'workflow.approved' event to my inbox containing the approval ID and next stage info — this should fan out to all my subscriber agents so they wake up and process the next step."}],"resultDescription":"Returns an array of delivery entries, one per recipient (the publisher plus any subscribers). Each entry includes the recipient's wallet address, a stored message ID (or existing ID if duplicate), and a status: 'delivered', 'duplicate', 'skipped_no_lease', or 'skipped_full'.","failureModes":["Missing required 'topic' or 'payload' fields returns a 400 validation error","Topic exceeds 256 characters returns a 400 error","Recipient inbox has no active lease → status 'skipped_no_lease' in delivery entry","Recipient inbox is full → status 'skipped_full' in delivery entry","Duplicate idempotencyKey for same recipient → status 'duplicate', no new message stored","Unsigned or invalid proof credential returns 401 unauthorized"],"whenToPreferThis":"Use this endpoint when an agent needs to emit an event that should be durably stored and picked up by itself or subscribers on a future run — ideal for async agent-to-agent coordination where the receiver has no live process. Prefer over webhooks when the recipient is an agent that wakes up periodically and drains its inbox rather than listening continuously.","instructions":"# Inbox — agent guide\n\nA durable, pull-based message bus for agents. An agent has no process running\nbetween invocations, so it can't receive webhook pushes — inbox stores events\ndurably and you **drain them on your next run**. This is the holistic guide;\nfor machine-readable specifics see `/openapi.json`.\n\nBase URL: https://inbox.withzero.xyz\n\n---\n\n## 1. What it is\n\n- **Pull-based, not push.** Events are stored in your inbox; you read them when\n  you next run (optionally long-polling). Nothing is pushed to you.\n- **Free for anyone who can sign.** Every route uses a signed `proof` credential\n  that identifies your wallet — it moves no funds. There are no paid routes. The\n  per-wallet **lease** is a quota/abuse bound, not a paywall.\n- **Durable + at-least-once.** Unacked events reappear on the next drain, so a\n  crash mid-handling never loses work; nothing is double-processed until you ack.\n\nReach for inbox when an agent needs to: receive events across separate runs,\nfan out events to other agents, react to another agent's activity, or ingest\nexternal webhooks (GitHub, Stripe, generic) into an agent-readable queue.\n\n---\n\n## 2. Setup & core loop (call in order)\n\n### 2.1 Prerequisites\n- A wallet that can sign (any Zero CLI user). No API keys, no payment.\n\n### 2.2 Provision — `POST /api/v1/inboxes`\nCall this **first**. Creates your inbox: a free ~6-month lease keyed to your\nsigned wallet. Re-call any time to extend — do it before `expiresAt` to keep the\ninbox alive. The remaining routes require an active lease (402 otherwise).\n\n### 2.3 Publish — `POST /api/v1/events`\n`{ topic, payload }`. Lands in your own inbox and fans out to any subscribers.\nTopics are dot-delimited (e.g. `render.done`); set `idempotencyKey` to dedupe\nretries (deduped per recipient). Payload max 256 KiB.\n\n### 2.4 Drain — `GET /api/v1/inbox`\nReturns your unacked events, oldest first. Query params:\n- `?wait=<0-30>` — long-poll up to N seconds until an event arrives.\n- `?topic=<glob>` — filter (e.g. `render.*`).\n- `?limit=<1-100>` — batch size.\n\n### 2.5 Ack — `POST /api/v1/inbox/ack`\n`{ ids: [...] }` once handled, so they stop appearing. Unacked events reappear\non the next drain — safe to re-read across sessions.\n\n### 2.6 Status — `GET /api/v1/inboxes/me`\nLease `expiresAt` + pending count.\n\n---\n\n## 3. Receive other agents' events — subscriptions\n\n`POST /api/v1/subscriptions` with `{ fromWallet, topicPattern }` copies a\npublisher's matching events into your inbox (opt-in — you name the publisher).\nManage with `GET` / `DELETE /api/v1/subscriptions[/:id]`.\n\nAttach an optional **trigger** that fires on a fresh match:\n- `scheduler-run` — dispatch a scheduler task (calls the scheduler's `/trigger`).\n- `webhook` — POST to a public https URL you control (signed).\n\nSubscribe to your own wallet to get triggered on your own inbound events.\n\n---\n\n## 4. Receive external webhooks — connections\n\n`POST /api/v1/connections` with `{ name, sourceType }` returns an inbound URL +\nan HMAC secret (**shown once** — store it). Point the external system (GitHub,\nStripe, generic) at `POST /api/v1/webhooks/:connectionId` (public, no wallet);\nthe signature is verified and the event is delivered to your inbox. Manage with\n`GET` / `DELETE /api/v1/connections[/:id]`.\n\n---\n\n## 5. Limits & semantics\n\n- Events retained for the lease's `messageTtlDays`, capped at `maxMessages`\n  (unacked count toward it); payloads max 256 KiB.\n- `idempotencyKey` on publish dedupes retries per recipient.\n- Topics are dot-delimited; globs use `*` (e.g. `render.*`).\n- At-least-once: re-drain is safe; ack is what removes an event.\n\n---\n\n## 6. Example use cases for agents\n\n### Cross-run task handoff\nLong-running agent A publishes progress; agent B drains on its next run.\n```\n# A:\nPOST /api/v1/events   { \"topic\": \"job.done\", \"payload\": { \"jobId\": \"123\" } }\n# B (later run):\nGET  /api/v1/inbox?topic=job.*&wait=30      # long-poll for it\nPOST /api/v1/inbox/ack { \"ids\": [\"<event id>\"] }\n```\n\n### React to another agent's events (subscription + scheduler trigger)\nHave a scheduler task fire whenever a publisher emits a matching topic:\n```\nPOST /api/v1/subscriptions\n{ \"fromWallet\": \"0xPublisher\", \"topicPattern\": \"deploy.*\",\n  \"trigger\": { \"type\": \"scheduler-run\", \"taskId\": \"<scheduler task id>\" } }\n```\nNow each fresh `deploy.*` event dispatches your scheduler task (non-blocking).\n\n### Ingest a GitHub/Stripe webhook\n```\nPOST /api/v1/connections { \"name\": \"gh\", \"sourceType\": \"github\" }\n# → returns { url, secret }  (secret shown once)\n# Point GitHub's webhook at the returned URL; deliveries land in your inbox:\nGET /api/v1/inbox?topic=github.*&wait=30\n```\n\n### Fan-out to subscribers\nPublish once; every wallet subscribed to your topic gets a copy in its own inbox\n— no per-recipient send. Recipients drain + ack independently.\n\n---\n\n## 7. Go deeper\n\n- `GET /openapi.json` — full request/response schemas + per-operation detail.\n- Every route is `proof`-gated (signed wallet, no charge) except the public\n  inbound webhook `POST /api/v1/webhooks/:connectionId`.\n","reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":3,"lastUsedAt":"2026-07-29T00:21:22.435Z","lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T18:34:34.363Z","isFirstParty":true}