Quick start: from API key to first message

A custom inbox source sends messages from any app into the member's Opami review inbox. They join the same pipeline as Gmail: filters, grouping, summaries and learning.

1. Create the app and its key

In Opami, add a custom app with the Inbox capability and create an API key for it. The key (opk_…) is shown once; Opami keeps only its hash. Note the app's id: it is the {id} in every URL below.

2. Send a message

curl -X POST https://app.opami.ai/v1/sources/$OPAMI_SOURCE_ID/messages \
  -H "Authorization: Bearer $OPAMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"A-1001","sender":{"kind":"email","value":"ana@example.com","display":"Ana"},"subject":"Hello","text":"First message from my app."}'

The answer is 202 {"message_id":"…","status":"received"}. Sending the same external_id again answers 200 with the first message_id and "duplicate": true, so retrying after a timeout is safe.

3. Follow it

curl https://app.opami.ai/v1/sources/$OPAMI_SOURCE_ID/messages/$MESSAGE_ID \
  -H "Authorization: Bearer $OPAMI_API_KEY"

status moves from received to processing to done (on an item in the review inbox), or failed.

4. Your own payload shape

If your app already sends JSON in its own shape, the member can confirm a field mapping in Opami (for example text from $.body.plain). From then on, payloads in your shape are accepted; a payload that cannot be mapped answers 422 with each failing field and the path it was read from.

5. Attach files

POST /v1/sources/{id}/uploads with { name, mime, bytes } answers an upload_id and a signed upload_url. PUT the bytes there, then list the upload_id in the message's uploads.

Limits and errors

Every endpoint answers errors as { "error": "<sentence>", "code": "<code>" }. Throttles are per client address (600 requests a minute) and per key (120 a minute); 429 carries Retry-After. Bodies over the endpoint's limit answer 413. A 503 is safe to retry with backoff. See the API reference for every endpoint.