# Publish Event to Inbox

> Publish Event to Inbox is a paid API for AI agents from inbox.withzero.xyz, paid per call via MPP, metered — billed by usage, status unknown (last checked 2026-09-14).

Publishes a named event with an arbitrary JSON payload into the caller's inbox, fanning out to any subscribers

## Facts

- Endpoint: POST https://inbox.withzero.xyz/api/v1/events
- Price: metered — billed by usage
- Payment: MPP
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 3
- Provider: inbox.withzero.xyz
- Website: https://inbox.withzero.xyz
- Canonical page: https://www.zero.xyz/c/inbox-withzero-xyz-publish-event-to-inbox-dbe41c17
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_pncavHkYkIMCtFMN3jJl8

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability inbox-withzero-xyz-publish-event-to-inbox-dbe41c17 -d '<json body>'
```

Example prompt: 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.

## When to prefer this

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.

## Known failure modes

- 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

## How this service works

Publish an event into your inbox. 📖 Full guide: https://inbox.withzero.xyz/llms.txt

## Output

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'.

## Example request

```json
{
 "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"
}
```

## Request schema (JSON Schema)

```json
{
 "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
}
```

## Response schema (JSON Schema)

```json
{
 "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
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/inbox-withzero-xyz-publish-event-to-inbox-dbe41c17/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from inbox.withzero.xyz](https://www.zero.xyz/host/inbox.withzero.xyz/llms.txt)