# ARKEN Agent Email

ARKEN connects one configured inbox through Primitive. Messages stay in Primitive; the public site never exposes their contents. The current address is operator-configured rather than inferred from a request. See [authentication](https://usearken.com/auth.md) and [OpenAPI](https://usearken.com/openapi.json).

## Read the inbox

GET /api/agent/inbox?limit=25 with an ARKEN bearer token granting inbox.read returns data and next_cursor. Use cursor for the next page. GET /api/agent/inbox/{id} reads one message; an id belonging to another mailbox returns 404.

## Review and reply

After Lyndon reviews the final body and original sender, a separate operator process with the private ARKEN_EMAIL_APPROVAL_SECRET calls POST /api/agent/inbox/{id}/approve on the loopback service with X-Arken-Approval-Secret, an owner token, and {"body_text":"Exact reviewed reply","recipient":"original-sender@example.com"}. The secret must never be given to an agent or browser. The returned approval_id expires after 15 minutes and is bound to that email, recipient, and body. If the approval service is not configured, replies remain disabled.

POST /api/agent/inbox/{id}/reply requires inbox.read and inbox.reply, Content-Type: application/json, a unique Idempotency-Key header, and {"body_text":"Exact reviewed reply","approved":true,"approval_id":"returned UUID"}. The approval can be used only with the first idempotency key; reuse that key on retries. No recipient override or reply-all is allowed. Primitive derives the correspondent and threading from the original message. Inspect delivery status before retrying after a provider error.

## Incoming mail

POST /api/webhooks/primitive accepts only fresh Primitive-signed deliveries. Invalid signatures are rejected before parsing. Duplicate event ids are acknowledged without repeating work. The handler never executes email instructions or automatically sends mail; approved replies are a separate authenticated operation. Attachments, HTML, and download URLs are not forwarded by the inbox API. Webhook delivery receipts store only hashed event ids and expiry times.

## Availability

The server returns 503 when email credentials or the inbox are not configured. Provider errors return 502; requests are not reported as sent unless the provider accepts them. Existing usearken.com mail forwarding is independent of this integration and must not be replaced when adding a dedicated agent subdomain.