Envelope Items

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 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.

Item type "event". This Item contains an error or default event payload 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 event
payload. Clients are required to generate an event identifier ahead of time
and set it at least in the Envelope headers. If the identifier mismatches
between the Envelope and payload, the Envelope header takes precedence.

Additional Item Headers:

None

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 the
transaction payload. Clients are required to generate an event identifier
ahead of time and set it at least in the Envelope headers. If the identifier
mismatches between the Envelope and payload, the Envelope header takes
precedence.

Additional Item Headers:

None

Item type "attachment". This Item contains a raw payload of an attachment file. It is always associated to an event or transaction.

Constraints:

This Item may occur multiple times per Envelope.
For minidump and apple crash report attachments, the corresponding "event" Item must be sent within the same Envelope.
Generic attachments can be ingested separately from their events. We recommend sending them in the same Envelope, which allows for more efficient rate limiting and filtering.
Generic attachments sent in separate Envelopes can be dropped independently of an event. To ensure consistent handling, consider sending them in the same request.
The Sentry server supports special attachments to ingest event payloads for backwards compatibility. These are not part of the official public API and the behavior should not be relied upon.

Envelope Headers:

event_id: UUID String, required. The identifier of the event or transaction.

Additional Item Headers:

filename: String, required. The name of the uploaded file without a path component.
attachment_type: String, optional. The special type of this attachment. Possible values are:

event.attachment (default): A standard attachment without special meaning.
event.minidump: A minidump file that creates an error event and is symbolicated. The file should start with the MDMP magic bytes.
event.applecrashreport: An Apple crash report file that creates an error event and is symbolicated.
unreal.context: An XML file containing UE4 crash meta data. During event ingestion, event contexts and extra fields are extracted from this file.
unreal.logs: A plain-text log file obtained from UE4 crashes. During event ingestion, the last logs are extracted into event breadcrumbs.
event.view_hierarchy: An JSON file with a predefined structure, see RFC #33.

content_type: String, optional. The content type of the attachment payload. Any MIME type may be used; the default is application/octet-stream.

Item type "session" contains a single session initialization or update to an existing session for Release Health.

See the sessions documentation for the payload details.

Constraints:

This Item may occur multiple times per Envelope.
Ingestion may limit the maximum number of Items per Envelope, see Ingestion.

Additional Item Headers:

None

Item type "sessions" contains buckets of pre-aggregated session counts.

See the sessions documentation for the payload details.

Constraints:

This Item may occur multiple times per Envelope.
Ingestion may limit the maximum number of Items per Envelope, see Ingestion.

Additional Item Headers:

None

Item type "statsd" contains metrics emissions in a superset of the statsd format.

See the metrics documentation for the payload details.

Constraints:

This Item may occur multiple times per Envelope.
Ingestion may limit the maximum number of Items per Envelope, see Ingestion.

Additional Item Headers:

None

Item type "metric_meta" contains per-metric meta data which is persisted alongside metrics in the system.

See the metrics documentation for the payload details.

Constraints:

This Item may occur multiple times per Envelope.
Ingestion may limit the maximum number of Items per Envelope, see Ingestion.

Additional Item Headers:

None

Item type "feedback". This Item contains an event payload encoded in JSON, with an additional feedback context object.

Example payload:

Copied

{
  "event_id": "9ec79c33ec9942ab8353589fcb2e04dc",
  "timestamp": "2011-05-02T17:41:36Z",
  "platform": "javascript",
  "level": "error",
  "contexts": {
    "feedback": {
      "contact_email": "john@example.com",
      "name": "John Smith",
      "message": "I love session replay!",
      "url": "https://sentry.io/replays/",
      "associated_event_id": "32fd1995636d446385016e2747623e11",
      "replay_id": "82840977e85b4ed3bc27f7b5b25cec15"
    }
  }
}

Payload Attributes

We only document attributes for the contexts.feedback object, which is required for this item type. For other attributes, see Event Payloads.

message: String, required. Comments of the user, describing what happened and/or sharing
feedback. The max length is 4096 characters.
contact_email: String, recommended. The email of the user.
name: String, optional. The name of the user.
url: String, optional. The URL of the referring webpage which may be used to search
for or set alerts on feedback.
associated_event_id: UUID String, optional. The identifier of an error event in the same project.
Use this to explicitly link a related error in the feedback UI.
replay_id: UUID String, optional. The identifier of a related session replay in the same
project. Sentry uses this ID to render a replay clip in the feedback UI.

Attaching Screenshots:

You can associate up to 1 screenshot/image with a feedback by sending an attachment item with an event_id corresponding to the feedback item. We recommend sending the items in the same Envelope.

Constraints:

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

Required Envelope Headers:

event_id: UUID String, required. Corresponds to the event_id field of the event
payload. It is not equal to the associated_event_id field in the feedback
context. Clients are required to generate an event identifier ahead of time
and set it at least in the Envelope headers. If the identifier mismatches
between the Envelope and payload, the Envelope header takes precedence.

Item type "user_report". This is an older way of submitting user feedback we are in the process of deprecating. It works by associating user information and comments with an event. If both the item and its associated event are accepted, we convert it to a user feedback.

The item contains a JSON payload like this:

Copied

{"event_id":"9ec79c33ec9942ab8353589fcb2e04dc","email":"john@me.com","name":"John Me","comments":"It broke."}\n

Payload Attributes

event_id: UUID String, required. The identifier of the associated event, ideally
an error.
email: String, recommended. The email of the user.
name: String, recommended. The name of the user.
comments: String, recommended. Comments of the user about what happened. The max length is 4096 characters.

Constraints:

This Item may occur once per Envelope.
User Reports can be ingested separately from their events. However, we recommend sending them in the same Envelope.
You may not associate multiple User Reports to the same event.
The event can not be more than 30 minutes old.
If the event does not exist in the same project or was never ingested, the report is discarded and never converted to feedback.

Envelope Headers:

event_id: UUID String, required. Corresponds to the event_id field of the payload.
If the identifier mismatches between the Envelope and payload, the Envelope
header takes precedence.

Additional Item Headers:

None

Item type "client_report" contains a client report payload encoded in JSON.

See the client reports documentation for the payload details.

Constraints:

This Item may occur multiple times per Envelope, but please avoid sending more client reports than necessary.
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

Item type "replay_event" contains a replay payload encoded in JSON.

See the replays documentation for the payload details.

Constraints:

This Item may occur at most once per Envelope.
This Item must be sent with a Replay Recording Item.

Envelope Headers:

None

Additional Item Headers:

None

Item type "replay_recording" contains a replay recording payload encoded in JSON or a gzipped JSON.

See the replays documentation for the payload details.

Constraints:

This Item may occur at most once per Envelope.
This Item must be sent with a Replay Event Item.

Envelope Headers:

None

Additional Item Headers:

length: integer, required. The size of the Replay recording payload

Item type "profile". This Item contains a profile payload encoded in JSON.

Constraints:

This Item may occur at most once per Envelope.
This Item needs to be in the same Envelope as the associated transaction.

Envelope Headers:

None

Additional Item Headers:

None

Item type "profile_chunk". This Item contains a profile_chunk (profile sample format V2) payload encoded in JSON.

Constraints:

None

Envelope Headers:

None

Additional Item Headers:

None

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

See the Check-Ins 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 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

Envelopes

Event Payloads

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").

How to contribute | Edit this page | Create a docs issue | Get support