---
title: "Envelope Items"
url: https://develop.sentry.dev/sdk/foundations/transport/envelope-items/
---

# Envelope Items

This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels.

Each Envelope consists of headers and a potentially empty list of Items, each with their own headers. Which Headers are required depends on the Items in an Envelope. This section describes all Item types and their respective required headers. It is worth noting that the list of Item types doesn't match the data categories used for [rate limiting](https://develop.sentry.dev/sdk/foundations/transport/rate-limiting.md#definitions) and client reports.

The type of an Item is declared in the `type` header, as well as the payload size in `length`. See Serialization Format for a list of common Item headers. The headers described in this section are **in addition to the common headers**.

## [Envelope Item Constraints](https://develop.sentry.dev/sdk/foundations/transport/envelope-items.md#envelope-item-constraints)

SDKs **MUST NOT** combine different types of telemetry data in the same envelope, because Relay enforces [rate limits](https://develop.sentry.dev/sdk/foundations/transport/rate-limiting.md) per [data category](https://develop.sentry.dev/sdk/foundations/transport/rate-limiting.md#definitions), and mixing types makes this enforcement more expensive. The exceptions to this rule are listed below.

The following constraints apply:

1. **Mutual exclusivity of event types**: [`event`](https://develop.sentry.dev/sdk/foundations/transport/envelope-items.md#event), [`transaction`](https://develop.sentry.dev/sdk/foundations/transport/envelope-items.md#transaction), and [`feedback`](https://develop.sentry.dev/sdk/telemetry/feedbacks.md#envelope-item-constraints) are mutually exclusive; an envelope **MUST** contain at most one. The envelope header's `event_id` **MUST** match the contained event, and other items such as attachments are implicitly scoped to it.
2. **Spans**: An envelope **MUST** contain at most one envelope item containing spans. The envelope **MUST** include a [DSC](https://develop.sentry.dev/sdk/foundations/trace-propagation/dynamic-sampling-context.md) header, and all spans **MUST** belong to the trace identified by that DSC; see [Span Buffer](https://develop.sentry.dev/sdk/telemetry/spans/span-buffer.md).
3. **Logs**: An envelope **MUST** contain at most one envelope item containing logs. SDKs **MAY** mix logs from different traces in the same envelope item. The envelope **MUST NOT** include a [DSC](https://develop.sentry.dev/sdk/foundations/trace-propagation/dynamic-sampling-context.md) header; see [Logs](https://develop.sentry.dev/sdk/telemetry/logs.md#log-envelope-item).
4. **Metrics**: An envelope **MUST** contain at most one envelope item containing metrics. SDKs **MAY** mix metrics from different traces in the same envelope item. The envelope **MUST NOT** include a [DSC](https://develop.sentry.dev/sdk/foundations/trace-propagation/dynamic-sampling-context.md) header; see [Metrics](https://develop.sentry.dev/sdk/telemetry/metrics.md#trace_metric-envelope-item).
5. **Sessions**: Multiple envelope items containing sessions **MAY** appear in a single envelope. SDKs **SHOULD** send session updates in the same envelope as their associated error or crash event; see [Sessions](https://develop.sentry.dev/sdk/telemetry/sessions.md#session-update-payload).
6. **Attachments**: Multiple envelope items containing attachments **MAY** appear in a single envelope. SDKs **SHOULD** send attachments in the same envelope as their associated event, so that if the event is filtered, the attachments are also filtered. For minidump and Apple crash report attachments, this is a **MUST**; see [Attachments](https://develop.sentry.dev/sdk/telemetry/attachments.md#standard-attachments).
7. **Check-ins**: An envelope **MUST** contain at most one envelope item containing a check-in; see [Check-Ins](https://develop.sentry.dev/sdk/telemetry/check-ins.md#envelope-constraints).
8. **Client reports**: Multiple envelope items containing client reports **MAY** appear in a single envelope; see [Client Reports](https://develop.sentry.dev/sdk/telemetry/client-reports.md#wire-format).
9. **Replays**: SDKs **MUST** send the `replay_event` and `replay_recording` envelope items together in the same envelope; see [Replay](https://develop.sentry.dev/sdk/telemetry/replays.md#replay-event-payload).
10. **User reports (deprecated)**: SDKs **SHOULD** send `user_report` envelope items in the same envelope as their associated event; see [User Reports](https://develop.sentry.dev/sdk/telemetry/user-reports.md#envelope-item).

## [Envelope Item Types](https://develop.sentry.dev/sdk/foundations/transport/envelope-items.md#envelope-item-types)

### [Event](https://develop.sentry.dev/sdk/foundations/transport/envelope-items.md#event)

Item type `"event"`. This Item contains an error or default [event payload](https://develop.sentry.dev/sdk/foundations/transport/event-payloads.md) encoded in JSON.

**Constraints:**

* This Item may occur at most once per Envelope.
* This Item is mutually exclusive with `"transaction"` Items.

**Envelope Headers:**

* `event_id`

  **UUID String, required.** Corresponds to the `event_id` field of the eventpayload. Clients are required to generate an event identifier ahead of timeand set it at least in the Envelope headers. If the identifier mismatchesbetween the Envelope and payload, the Envelope header takes precedence.

**Additional Item Headers:**

*None*

## [Transaction](https://develop.sentry.dev/sdk/foundations/transport/envelope-items.md#transaction)

Item type `"transaction"`. This Item contains a transaction payload encoded in JSON.

**Constraints:**

* This Item may occur at most once per Envelope.
* This Item is mutually exclusive with `"event"` Items.

**Envelope Headers:**

* `event_id`

  **UUID String, required.** Corresponds to the `event_id` field of thetransaction payload. Clients are required to generate an event identifierahead of time and set it at least in the Envelope headers. If the identifiermismatches between the Envelope and payload, the Envelope header takesprecedence.

* `trace`

  **Dynamic sampling context, optional** Transaction events can optionally provide a[Dynamic sampling context](https://develop.sentry.dev/sdk/telemetry/traces/dynamic-sampling-context.md).

**Additional Item Headers:**

*None*

## [Attachment](https://develop.sentry.dev/sdk/foundations/transport/envelope-items.md#attachment)

Item type `"attachment"`. See the [Attachments](https://develop.sentry.dev/sdk/telemetry/attachments.md) spec for full documentation of standard attachments, attachment placeholders, and trace attachments.

## [Check-Ins](https://develop.sentry.dev/sdk/foundations/transport/envelope-items.md#check-ins)

Item type `"check_in"` contains a check-in payload encoded as JSON.

See the [Check-Ins](https://develop.sentry.dev/sdk/telemetry/check-ins.md) documentation for the payload details.

**Constraints:**

* This Item may occur at most once per Envelope.
* This Item can either be included in an Envelope with other Items, or it may be sent by itself.

**Envelope Headers:**

*None*

**Additional Item Headers:**

*None*

### [Reserved Types](https://develop.sentry.dev/sdk/foundations/transport/envelope-items.md#reserved-types)

Reserved types may not be written by any implementation. They are reserved for future or internal use. This is the exhaustive list of reserved Item types:

* `security`
* `unreal_report`
* `form_data`