Emails

Get the conversation an email belongs to

Changed on

Returns the full conversation the given inbound email belongs to, as ordered, ready-to-prompt turns WITH bodies. It resolves the thread from the email and returns every message oldest-first, so an agent that received an email can pass messages straight to a chat model in one call instead of walking /threads/{id} plus /emails/{id} and /sent-emails/{id} per message.

Each message carries a direction (inbound | outbound) and a derived role: inbound -> user, outbound -> assistant (your own prior replies). The role mapping assumes the caller owns the outbound side, which is the agent-reply case this exists for. If the email has no thread yet (a brand-new message), the conversation is just that one message as a single user turn.

The message list is capped; check truncated to detect when older messages were omitted. Consecutive same-role turns are not merged here; that normalization is model-specific and left to the caller.

Pass since for an incremental read. since=start returns the full conversation plus a cursor. Sending that cursor back as since returns only the messages created or changed after it, oldest first, with the same per-message shape, and a new cursor. Without since the response carries no cursor and no per-message status.

get/emails/{id}/conversation

Request

  • Base URL: https://api.primitive.dev/v1
  • URL: https://api.primitive.dev/v1/emails/{id}/conversation
  • Auth: HTTP bearer

Query parameters

sincestring

Incremental read position. Either the literal start or a cursor returned by a previous read of this endpoint. Any other value returns 400 validation_error.

With start, the response holds every message the read without since would return, plus cursor. With a cursor, messages holds only the messages created or changed after it, oldest first. A change includes an inbound message becoming visible or its body being filled, withheld or discarded, and a delivery status change on an outbound message. thread_id, subject, message_count and truncated always describe the whole conversation, not the returned messages.

The cursor is an opaque string. Send it back verbatim and do not parse it or build one; its format can change. A message can be returned again by a later read (for example while older writes are still committing), so upsert messages by id. Deleted messages are not reported; a periodic since=start read (or a read without since) reconciles.

Response

Conversation

successboolean required

Changes

  • 64cd1e7c6ac2Revision changes
    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

  • 52138fa51360Revision changes
    • info

      removed the invalid_signup_code enum value from the / response property for the response status

    • info

      removed the invalid_signup_code enum value from the / response property for the response status

    • info

      removed the invalid_signup_code enum value from the / response property for the response status