# Acknowledge (ACK) Inbox Events

> Acknowledge (ACK) Inbox Events is a free API for AI agents from inbox.withzero.xyz, Free, status unknown (last checked 2026-09-14).

Marks one or more drained inbox events as handled so they no longer appear in subsequent drain calls.

## Facts

- Endpoint: POST https://inbox.withzero.xyz/api/v1/inbox/ack
- Price: Free
- 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-acknowledge-ack-inbox-events-8b7561da
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_NaHMnBhW6uJ1xFeSejkt_

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-acknowledge-ack-inbox-events-8b7561da -d '<json body>'
```

Example prompt: I just finished processing the events I drained from my inbox — mark these message IDs as handled so they stop appearing: ['3f2504e0-4f89-11d3-9a0c-0305e82c3301', 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11'].

## When to prefer this

Use this endpoint after draining events from your inbox (GET /api/v1/inbox) and successfully processing them. This is the final step in the drain-process-ack lifecycle. Call this to prevent already-handled events from reappearing in future drain calls. Supports up to 100 message IDs per call for efficient batch acknowledgment.

## Known failure modes

- Empty or missing 'ids' array returns a validation error
- More than 100 IDs in one call exceeds maxItems limit and is rejected
- Malformed UUIDs that don't match the required pattern cause a 400 error
- Invalid or expired signed proof credential causes authentication failure
- IDs that don't belong to the caller's inbox are silently ignored or rejected

## How this service works

Mark drained events handled so they stop appearing. 📖 Full guide: https://inbox.withzero.xyz/llms.txt

## Output

Returns a JSON object with an 'acked' field containing the count of messages that were newly acknowledged (i.e., transitioned from unacked to acked state). Messages already acked are not double-counted.

## Example request

```json
{
 "ids": [
  "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
  "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"
 ]
}
```

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "ids"
 ],
 "properties": {
  "ids": {
   "type": "array",
   "items": {
    "type": "string",
    "format": "uuid",
    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
   },
   "maxItems": 100,
   "minItems": 1,
   "description": "Message ids to mark handled."
  }
 },
 "additionalProperties": false
}
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "acked"
 ],
 "properties": {
  "acked": {
   "type": "number",
   "description": "Number of messages newly acked."
  }
 },
 "additionalProperties": false
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/inbox-withzero-xyz-acknowledge-ack-inbox-events-8b7561da/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)