# Message Headers


The headers of a message are similar to HTTP headers and contain metadata about the message being sent over the queueing system. This document describes the headers used by NServiceBus. To learn more about how to use custom headers, see the documentation on [manipulating message headers](/nservicebus/messaging/header-manipulation.md).


## Timestamp format


For all timestamp message headers, the format is `yyyy-MM-dd HH:mm:ss:ffffff Z`, where the time is UTC. The helper class `DateTimeOffsetHelper` supports converting from UTC to wire format and vice versa by using the `ToWireFormattedString(DateTimeOffset)` and `ToDateTimeOffset(string)` methods.


### ISO 8601 format

This is NOT the [ISO 8601 format](https://nl.wikipedia.org/wiki/ISO_8601) but a custom format.

Differences:

1. a `T` between date and time
2. uses a `.` between seconds and milli/microseconds
3. no space between the timestamp and the `Z`

```
ISO 8601:    yyyy-MM-ddTHH:mm:ss.ffffffZ
NServiceBus: yyyy-MM-dd HH:mm:ss:ffffff Z
```

When doing native intergration and there is a need to parse the timestamp the `.` as second and milli/microsecond separator is where regular timestamp parsers often fail.

## Transport headers

### NServiceBus.NonDurableMessage

The `NonDurableMessage` header controls [non-durable messaging](non-durable-messaging.md) persistence behavior of in-flight messages. The behavior is transport-specific, but the intent is to not store the message durably on disk and only keep it in memory.

### NServiceBus.TimeToBeReceived

The `TimeToBeReceived` header [controls when a message becomes obsolete and can be discarded](discard-old-messages.md). The behavior is transport-dependent.

### NServiceBus.Transport.Encoding

States what type of body serialization is used.

It is used only by the legacy Azure Service Bus transport (`NServiceBus.Azure.Transports.WindowsAzureServiceBus` package), which is no longer supported.

## Serialization headers

The following headers include information for the receiving endpoint on the [message serialization](/nservicebus/serialization/index.md) option that was used.

### NServiceBus.ContentType

The type of serialization used for the message, for example, `text/xml`, `text/json`, `application/json`, or `application/json; systemjson`.

In some cases, the `NServiceBus.Version` header may be useful for determining how to use the value in this header appropriately.

> [!WARNING]
> Although this header mimicks the [HTTP Content-Type header](https://www.rfc-editor.org/rfc/rfc9110.html#name-content-type) the values are case-sensitive. The header value does not behave like HTTP headers where everything after `;` is used to order and match the best qualified (application/json) serializer. Adding a suffix like `; systemjson` requires **all** endpoints involved to use this full key (for example: `application/json; systemjson`).

### NServiceBus.EnclosedMessageTypes

The fully qualified .NET type name of the enclosed message(s). The receiving endpoint will use this type when deserializing an incoming message. Depending on the [versioning strategy](/samples/versioning/index.md) the type can be specified in the following ways:

* Full type name: `Namespace.ClassName`.
* Assembly qualified name: `Namespace.ClassName, AssemblyName, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null`.

See the [message type detection documentation](/nservicebus/messaging/message-type-detection.md) for more details.

## Messaging interaction headers

The following headers enable different messaging interaction patterns, such as Request-Response.

### NServiceBus.MessageId

A [unique ID for the current message](/nservicebus/messaging/message-identity.md).

### NServiceBus.CorrelationId

NServiceBus implements the [Correlation Identifier](https://www.enterpriseintegrationpatterns.com/patterns/messaging/CorrelationIdentifier.html) pattern by using a `Correlation Id` header.

Message correlation connects request messages with their corresponding response messages. The `Correlation Id` of the response message is the `Correlation Id` of its corresponding request message. Each outgoing message which is sent outside of a message handler will have its `Correlation Id` set to its `Message Id`.

An example of Correlation Identifier usage within NServiceBus can be found in [callbacks](/nservicebus/messaging/callbacks.md).

Messages sent from a [saga](/nservicebus/sagas/index.md) using the `ReplyToOriginator` method will have their `Correlation Id` set based on the message which caused the saga to be created. See [Notifying callers of status](/nservicebus/sagas/index.md#notifying-callers-of-status) for more information about the `ReplyToOriginator` method.

### CorrId

`CorrId` is an MSMQ specific header semantically identical to `NServiceBus.CorrelationId`. It is included only for backward compatibility with endpoints running version 3 or older of NServiceBus.

### NServiceBus.ConversationId

The identifier of the conversation that this message is part of. It enables the tracking of message flows that span more than one message exchange. `ConversationId`, `RelatedTo`, `OriginatingEndpoint`, and `ProcessingEndpoint` fields allow [ServicePulse](/servicepulse/message-details.md#messages-with-audited-conversation-data-flow-diagram) to reconstruct the entire message flow.

The first message **sent** in a new flow is automatically assigned a unique `ConversationId` that gets propagated to all the messages that are sent afterward, forming a _conversation_. Each message sent within a conversation has a `RelatedTo` value that identifies the message that caused it to be sent.

The `ConversationId` must be assigned manually in cases where NServiceBus can't infer when messages belong to the same conversation. For example, when a `CancelOrder` message must be part of an existing order conversation, the `OrderId` can be used as the `ConversationId`. Manually assigning a `ConversationId` to the message being sent can be achieved by overriding the header with a custom value:

<!-- snippet: override-conversation-id -->

```cs
var sendOptions = new SendOptions();
sendOptions.SetHeader(Headers.ConversationId, "MyCustomConversationId/" + System.Guid.NewGuid());
await context.Send(new MyMessage(), sendOptions);
```

<!-- endsnippet -->

To get full control over the `ConversationId`, a custom convention can be registered:

<!-- snippet: custom-conversation-id-convention -->

```cs
config.CustomConversationIdStrategy(context =>
{
    if (context.Message.Instance is CancelOrder)
    {
        //use the order id as the conversation id
        return ConversationId.Custom("Order/" + ((CancelOrder)context.Message.Instance).OrderId);
    }

    //use the default generated id
    return ConversationId.Default;
});
```

<!-- endsnippet -->

This will automatically be invoked for all sent messages so they use the custom `ConversationId`, and it no longer needs to be manually set for each individual message. This approach is useful when a given rule or custom attribute should be applied to all sent messages.

> [!NOTE]
> This is not invoked for incoming messages.


> [!WARNING]
> Attempting to override an existing Conversation ID is not supported and will produce the following error:
> ```
> Cannot set the NServiceBus.ConversationId header to 'XXXXX' as it cannot override the incoming header value ('2f4076a0-d8de-4297-9d18-a830015dd42a').
> ```

> [!NOTE]
> `Conversation Id` is very similar to `Correlation Id`. Both headers are copied to each new message that an endpoint produces. Whereas `Conversation Id` is always copied from the incoming message being handled, `Correlation Id` can come from another source (such as when replying from a saga using `ReplyToOriginator(...)`).

#### Starting a new conversation

In some scenarios though, starting a new conversation might be desirable. For example, a batch import that reads thousands of records and starts a workflow on each one would normally result in a giant visualization, where it would be more appropriate for each record to be a new conversation.

Starting a new conversation can be done with the help of SendOptions:

<!-- snippet: new-conversation-id -->

```cs
var sendOptions = new SendOptions();
sendOptions.StartNewConversation();

await context.Send(new CancelOrder(), sendOptions);
```

<!-- endsnippet -->

A custom `Conversation ID` can also be provided:

<!-- snippet: new-conversation-custom-id -->

```cs
var sendOptions = new SendOptions();
sendOptions.StartNewConversation("MyCustomConversationId/" + System.Guid.NewGuid());

await context.Send(new CancelOrder(), sendOptions);
```

<!-- endsnippet -->



### NServiceBus.RelatedTo

The `MessageId` that caused the current message to be sent. Whenever a message is sent or published from inside a message handler, its `RelatedTo` header is set to the `MessageId` of the incoming message being handled.

> [!NOTE]
> For a single request-response interaction, `Correlation Id` and `RelatedTo` are very similar. Both headers can correlate the response message back to the request message. Once a _conversation_ is longer than a single request-response interaction, `Correlation Id` can correlate a response to the original request. `RelatedTo` can only correlate a message to the previous message in the same _conversation_.


### NServiceBus.MessageIntent

Message intent can have one of the following values:

| Value       | Description                                                                                                                                                        |
|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Send        | Regular point-to-point send. Note that messages sent to the error queue will also have a `Send` intent                                                             |
| Publish     | The message is an event that has been published and will be sent to all subscribers.                                                                               |
| Subscribe   | A [control message](#messaging-interaction-headers-nservicebus-messageintent) indicating that the source endpoint wants to subscribe to a specific message.   |
| Unsubscribe | A [control message](#messaging-interaction-headers-nservicebus-messageintent) indicating that the source endpoint wants to unsubscribe to a specific message. |
| Reply       | The message has been initiated by doing a Reply or a Return from within a Handler or a Saga.                                                                       |

### NServiceBus.ControlMessage

Indicates that the message is a control message, i.e., it has no body, and the intent of the message and any data are transmitted in the message headers.

### NServiceBus.ReplyToAddress

Downstream message [handlers](/nservicebus/handlers/index.md) or [sagas](/nservicebus/sagas/index.md) use this value as the reply queue address when replying or returning a message.

## Send headers

When a message is sent, the headers will be as follows:

<!-- snippet: HeaderWriterSend -->

```txt
$.diagnostics.originating.hostid = daaf5ebc8d6a51b7b0dccdd8b15c3626
NServiceBus.ContentType = application/json
NServiceBus.ConversationId = 1d5fc7ad-0f38-4172-a469-b43b0169b466
NServiceBus.CorrelationId = 43e9c0c6-57a8-4513-b15a-b43b0169b465
NServiceBus.EnclosedMessageTypes = Core.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = 43e9c0c6-57a8-4513-b15a-b43b0169b465
NServiceBus.MessageIntent = Send
NServiceBus.OpenTelemetry.StartNewTrace = False
NServiceBus.OriginatingEndpoint = HeaderWriterSend
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ReplyToAddress = HeaderWriterSend
NServiceBus.TimeSent = 2026-04-29 21:56:55:590807 Z
NServiceBus.Version = 10.2.0
```

<!-- endsnippet -->

In the above example, the headers are for a Send operation, and hence, the `MessageIntent` header is `Send`. If the message were published instead, the `MessageIntent` header would be `Publish`.

## Reply headers

When replying to a message:

* The `MessageIntent` is `Reply`.
* The `RelatedTo` will be the same as the initiating `MessageID`.
* The `ConversationId` will be the same as the initiating `ConversationId`.
* The `CorrelationId` will be the same as the initiating `CorrelationId`.

### Example reply headers

Given an initiating message with the following headers:

<!-- snippet: HeaderWriterReplySending -->

```txt
$.diagnostics.originating.hostid = daaf5ebc8d6a51b7b0dccdd8b15c3626
NServiceBus.ContentType = application/json
NServiceBus.ConversationId = 3a0fb0c4-8b60-4cad-a6db-b43b016d03ef
NServiceBus.CorrelationId = 0a96c254-e745-4296-b1a5-b43b016d03ee
NServiceBus.EnclosedMessageTypes = Core.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = 0a96c254-e745-4296-b1a5-b43b016d03ee
NServiceBus.MessageIntent = Send
NServiceBus.OpenTelemetry.StartNewTrace = False
NServiceBus.OriginatingEndpoint = HeaderWriterReply
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ReplyToAddress = HeaderWriterReply
NServiceBus.TimeSent = 2026-04-29 22:08:58:819617 Z
NServiceBus.Version = 10.2.0
```

<!-- endsnippet -->

The headers of the reply message will be:

<!-- snippet: HeaderWriterReplyReplying -->

```txt
$.diagnostics.originating.hostid = daaf5ebc8d6a51b7b0dccdd8b15c3626
NServiceBus.ContentType = application/json
NServiceBus.ConversationId = 3a0fb0c4-8b60-4cad-a6db-b43b016d03ef
NServiceBus.CorrelationId = 0a96c254-e745-4296-b1a5-b43b016d03ee
NServiceBus.EnclosedMessageTypes = Core.Headers.Writers.MyNamespace.MessageToReply, MyAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = 32ac55a7-5a66-4ca4-94ec-b43b016d03f9
NServiceBus.MessageIntent = Reply
NServiceBus.OriginatingEndpoint = HeaderWriterReply
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.RelatedTo = 0a96c254-e745-4296-b1a5-b43b016d03ee
NServiceBus.ReplyToAddress = HeaderWriterReply
NServiceBus.TimeSent = 2026-04-29 22:08:58:850190 Z
NServiceBus.Version = 10.2.0
```

<!-- endsnippet -->

## Publish headers

When a message is published, the headers will be as follows:

<!-- snippet: HeaderWriterPublish -->

```txt
$.diagnostics.originating.hostid = daaf5ebc8d6a51b7b0dccdd8b15c3626
NServiceBus.ContentType = application/json
NServiceBus.ConversationId = 35b4c487-97b1-47cb-9181-b43b016d4482
NServiceBus.CorrelationId = da253bc4-68bd-42f3-ac7f-b43b016d4482
NServiceBus.EnclosedMessageTypes = Core.Headers.Writers.MyNamespace.MessageToPublish, MyAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = da253bc4-68bd-42f3-ac7f-b43b016d4482
NServiceBus.MessageIntent = Publish
NServiceBus.OpenTelemetry.StartNewTrace = True
NServiceBus.OriginatingEndpoint = HeaderWriterPublish
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ReplyToAddress = HeaderWriterPublish
NServiceBus.TimeSent = 2026-04-29 22:09:53:925402 Z
NServiceBus.Version = 10.2.0
```

<!-- endsnippet -->

## Return from a handler

When returning a message instead of replying:

* The Return has the same points as the Reply example above but with some additions.
* The `ReturnMessage.ErrorCode` contains the value supplied to the `Bus.Return` method.

### Example return headers

Given an initiating message with the following headers:

<!-- snippet: HeaderWriterReturnSending -->

```txt
$.diagnostics.originating.hostid = daaf5ebc8d6a51b7b0dccdd8b15c3626
NServiceBus.ContentType = application/json
NServiceBus.ConversationId = 418b54ae-859f-48e2-ae5c-b43b016ca105
NServiceBus.CorrelationId = dd8dda40-2158-4111-9041-b43b016ca104
NServiceBus.EnclosedMessageTypes = Core.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = dd8dda40-2158-4111-9041-b43b016ca104
NServiceBus.MessageIntent = Send
NServiceBus.OpenTelemetry.StartNewTrace = False
NServiceBus.OriginatingEndpoint = HeaderWriterReturn
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ReplyToAddress = HeaderWriterReturn
NServiceBus.TimeSent = 2026-04-29 22:07:34:413876 Z
NServiceBus.Version = 10.2.0
```

<!-- endsnippet -->

The headers of the reply message will be:

<!-- snippet: HeaderWriterReturnReturning -->

```txt
$.diagnostics.originating.hostid = daaf5ebc8d6a51b7b0dccdd8b15c3626
NServiceBus.ControlMessage = True
NServiceBus.ConversationId = 418b54ae-859f-48e2-ae5c-b43b016ca105
NServiceBus.CorrelationId = dd8dda40-2158-4111-9041-b43b016ca104
NServiceBus.MessageId = 7a8293e2-6440-4072-8dc0-b43b016ca10f
NServiceBus.MessageIntent = Reply
NServiceBus.OriginatingEndpoint = HeaderWriterReturn
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.RelatedTo = dd8dda40-2158-4111-9041-b43b016ca104
NServiceBus.ReplyToAddress = HeaderWriterReturn
NServiceBus.ReturnMessage.ErrorCode = 100
NServiceBus.TimeSent = 2026-04-29 22:07:34:444507 Z
NServiceBus.Version = 10.2.0
```

<!-- endsnippet -->

## Timeout headers

### NServiceBus.ClearTimeouts

This is a header to indicate that the contained [control message](#messaging-interaction-headers-nservicebus-messageintent) requests that timeouts be cleared for a given saga.

### NServiceBus.Timeout.Expire

A timestamp that indicates when a timeout should be fired.

### NServiceBus.Timeout.RouteExpiredTimeoutTo

The queue name to which a timeout should be routed back to when it expires.

### NServiceBus.IsDeferredMessage

A header to indicate that this message resulted from a message deferral.

## Saga-related headers

When a message is dispatched from within a saga, the message will contain the following headers:

* `OriginatingSagaId`: matches the ID used as the index for the saga data stored in persistence.
* `OriginatingSagaType`: the fully qualified type name of the saga that sent the message.

### Example "send from saga" headers

<!-- snippet: HeaderWriterSagaSending -->

```txt
$.diagnostics.originating.hostid = daaf5ebc8d6a51b7b0dccdd8b15c3626
NServiceBus.ContentType = application/json
NServiceBus.ConversationId = 4119c812-d313-46c0-8b02-b43b016ccb4a
NServiceBus.CorrelationId = 60ae1074-a3ac-4047-be45-b43b016ccb49
NServiceBus.EnclosedMessageTypes = Core.Headers.Writers.MyNamespace.SendFromSagaMessage, MyAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = 4cb483eb-a01a-41f3-92df-b43b016ccb55
NServiceBus.MessageIntent = Send
NServiceBus.OpenTelemetry.StartNewTrace = False
NServiceBus.OriginatingEndpoint = HeaderWriterSaga
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.OriginatingSagaId = 14cfe524-7377-1367-6615-9061c2a79edd
NServiceBus.OriginatingSagaType = Core.Headers.Writers.MyNamespace.Saga1, MyAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.RelatedTo = 60ae1074-a3ac-4047-be45-b43b016ccb49
NServiceBus.ReplyToAddress = HeaderWriterSaga
NServiceBus.TimeSent = 2026-04-29 22:08:10:516632 Z
NServiceBus.Version = 10.2.0
```

<!-- endsnippet -->

### Replying to a saga

A message reply is performed from a saga will have the following headers:

* The send headers are the same as a standard reply header with a few additions.
* Since this reply is from a secondary saga, then `OriginatingSagaId` and `OriginatingSagaType` will match the second saga.
* Since this is a reply to the initial saga, the headers will contain `SagaId` and `SagaType` headers matching the initial saga.

### Example "replying to a saga" headers

#### Via calling Bus.Reply

<!-- snippet: HeaderWriterSagaReplying -->

```txt
$.diagnostics.originating.hostid = daaf5ebc8d6a51b7b0dccdd8b15c3626
NServiceBus.ContentType = application/json
NServiceBus.ConversationId = 4119c812-d313-46c0-8b02-b43b016ccb4a
NServiceBus.CorrelationId = 60ae1074-a3ac-4047-be45-b43b016ccb49
NServiceBus.EnclosedMessageTypes = Core.Headers.Writers.MyNamespace.ReplyFromSagaMessage, MyAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = 682e3fce-d786-4a22-9d1d-b43b016ccb5b
NServiceBus.MessageIntent = Reply
NServiceBus.OriginatingEndpoint = HeaderWriterSaga
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.OriginatingSagaId = b8b235ac-2601-0e5f-0216-3d2b330d90b0
NServiceBus.OriginatingSagaType = Core.Headers.Writers.MyNamespace.Saga2, MyAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.RelatedTo = 4cb483eb-a01a-41f3-92df-b43b016ccb55
NServiceBus.ReplyToAddress = HeaderWriterSaga
NServiceBus.SagaId = 14cfe524-7377-1367-6615-9061c2a79edd
NServiceBus.SagaType = Core.Headers.Writers.MyNamespace.Saga1, MyAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.TimeSent = 2026-04-29 22:08:10:537452 Z
NServiceBus.Version = 10.2.0
```

<!-- endsnippet -->

#### Via calling Saga.ReplyToOriginator

<!-- snippet: HeaderWriterSagaReplyingToOriginator -->

```txt
$.diagnostics.originating.hostid = daaf5ebc8d6a51b7b0dccdd8b15c3626
NServiceBus.ContentType = application/json
NServiceBus.ConversationId = 4119c812-d313-46c0-8b02-b43b016ccb4a
NServiceBus.CorrelationId = 4cb483eb-a01a-41f3-92df-b43b016ccb55
NServiceBus.EnclosedMessageTypes = Core.Headers.Writers.MyNamespace.ReplyToOriginatorFromSagaMessage, MyAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = 161f3ddb-e7b6-407f-835f-b43b016ccb5b
NServiceBus.MessageIntent = Reply
NServiceBus.OriginatingEndpoint = HeaderWriterSaga
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.OriginatingSagaId = b8b235ac-2601-0e5f-0216-3d2b330d90b0
NServiceBus.OriginatingSagaType = Core.Headers.Writers.MyNamespace.Saga2, MyAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.RelatedTo = 4cb483eb-a01a-41f3-92df-b43b016ccb55
NServiceBus.ReplyToAddress = HeaderWriterSaga
NServiceBus.TimeSent = 2026-04-29 22:08:10:537889 Z
NServiceBus.Version = 10.2.0
```

<!-- endsnippet -->

### Requesting a timeout from a saga

When requesting a timeout from a saga:

* The `OriginatingSagaId`, `OriginatingSagaType`, `SagaId` and `SagaType` will all match the Saga that requested the Timeout.
* The `Timeout.RouteExpiredTimeoutTo` header contains the queue name for where the callback for the timeout should be sent.
* The `Timeout.Expire` header contains the timestamp for when the timeout should fire.

#### Example timeout headers

<!-- snippet: HeaderWriterSagaTimeout -->

```txt
$.diagnostics.originating.hostid = 8cf0a8f78f9cd1885699777c83eb631e
CorrId = cb4c79a4-476c-4e64-aff1-a5eb011ad6e5\0
NServiceBus.ContentType = text/xml
NServiceBus.ConversationId = dbaf0a21-9b6a-49bd-ae76-a5eb011ad6df
NServiceBus.CorrelationId = cb4c79a4-476c-4e64-aff1-a5eb011ad6e5
NServiceBus.EnclosedMessageTypes = Core6.Headers.Writers.MyNamespace.TimeoutFromSaga, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.IsSagaTimeoutMessage = True
NServiceBus.MessageId = 433d5c9f-4968-4bf9-9c7e-a5eb011ad72a
NServiceBus.MessageIntent = Send
NServiceBus.OriginatingEndpoint = HeaderWriterSagaV6
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.OriginatingSagaId = 25b7653a-5612-4e9e-b78f-a5eb011ad729
NServiceBus.OriginatingSagaType = Core6.Headers.Writers.MyNamespace.Saga2, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.RelatedTo = cb4c79a4-476c-4e64-aff1-a5eb011ad6e5
NServiceBus.ReplyToAddress = HeaderWriterSagaV6@MACHINENAME
NServiceBus.SagaId = 25b7653a-5612-4e9e-b78f-a5eb011ad729
NServiceBus.SagaType = Core6.Headers.Writers.MyNamespace.Saga2, MyAssembly, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.Timeout.Expire = 2016-04-17 07:09:47:444081 Z
NServiceBus.Timeout.RouteExpiredTimeoutTo = HeaderWriterSagaV6@MACHINENAME
NServiceBus.TimeSent = 2016-04-17 07:09:47:443081 Z
NServiceBus.Version = 6.0.0
```

<!-- endsnippet -->

## Defer a message

When deferring, the message will have similar headers compared to a _send_, but will be delivered later.

In NServiceBus version 7.7 and above, the `DeliverAt` header will also be added containing the time when the message was targeted to be delivered.


### Example defer headers

<!-- snippet: HeaderWriterDefer -->

```txt
$.diagnostics.originating.hostid = daaf5ebc8d6a51b7b0dccdd8b15c3626
NServiceBus.ContentType = application/json
NServiceBus.ConversationId = f777b9ea-ee0d-4a22-9489-b43b016db0cc
NServiceBus.CorrelationId = c8c492ed-bb3f-4ecd-9d8c-b43b016db0cc
NServiceBus.DeliverAt = 2026-04-29 22:11:26:340982 Z
NServiceBus.EnclosedMessageTypes = Core.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = c8c492ed-bb3f-4ecd-9d8c-b43b016db0cc
NServiceBus.MessageIntent = Send
NServiceBus.OpenTelemetry.StartNewTrace = False
NServiceBus.OriginatingEndpoint = HeaderWriterDefer
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ReplyToAddress = HeaderWriterDefer
NServiceBus.TimeSent = 2026-04-29 22:11:26:330982 Z
NServiceBus.Version = 10.2.0
```

<!-- endsnippet -->

## Diagnostic and informational headers

Headers used to give visibility into the "where," "when," and "by whom" of a message. They are used by [ServiceControl](/servicecontrol/index.md) and [ServicePulse](/servicepulse/index.md).

### $.diagnostics

The [host details](/nservicebus/hosting/override-hostid.md) of the endpoint where the message was being processed. This header contains three parts:

* `$.diagnostics.hostdisplayname`
* `$.diagnostics.hostid`
* `$.diagnostics.originating.hostid`

### NServiceBus.TimeSent

The timestamp when the message was sent, used by the [Performance Counters](/monitoring/metrics/performance-counters.md).

### NServiceBus.DeliverAt

The timestamp when the message should be delivered. Used for more accurate calculation of [critical time](/monitoring/metrics/definitions.md#metrics-captured-critical-time).

### NServiceBus.OriginatingEndpoint

The endpoint name the message was sent from.

> [!NOTE]
> Used for linking messages in ServicePulse. See [NServiceBus.ConversationId](#messaging-interaction-headers-nservicebus-conversationid)

### NServiceBus.OriginatingMachine

The machine name the message was sent from.

### NServiceBus.Version

The NServiceBus version number.

## OpenTelemetry-related headers

These headers are added when [OpenTelemetry](/nservicebus/operations/opentelemetry.md) is enabled for an endpoint, in accordance with the [W3C Trace Context specification](https://www.w3.org/TR/trace-context):

* [`traceparent`](https://www.w3.org/TR/trace-context/#traceparent-header)
* [`tracestate`](https://www.w3.org/TR/trace-context/#tracestate-header)
* [`baggage`](https://www.w3.org/TR/baggage/#baggage-http-header-format)

## Audit headers

Headers added when a message is [audited](/nservicebus/operations/auditing.md).

### NServiceBus.ProcessingEnded

The timestamp when the processing of a message ended.

### NServiceBus.ProcessingEndpoint

Name of the endpoint where the message was processed.

> [!NOTE]
> Used for linking messages in ServicePulse. See [NServiceBus.ConversationId](#messaging-interaction-headers-nservicebus-conversationid)

### NServiceBus.ProcessingMachine

The machine name of the endpoint where the message was processed.

### NServiceBus.ProcessingStarted

The timestamp when the processing of this message started.

### Example audit headers

Given an initiating message with the following headers:

<!-- snippet: HeaderWriterAuditSend -->

```txt
$.diagnostics.originating.hostid = daaf5ebc8d6a51b7b0dccdd8b15c3626
NServiceBus.ContentType = application/json
NServiceBus.ConversationId = 5520abbd-7b30-4914-a3d4-b43b016d917e
NServiceBus.CorrelationId = 4ad00d77-6e0d-44cc-bd3e-b43b016d917d
NServiceBus.EnclosedMessageTypes = Core.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = 4ad00d77-6e0d-44cc-bd3e-b43b016d917d
NServiceBus.MessageIntent = Send
NServiceBus.OpenTelemetry.StartNewTrace = False
NServiceBus.OriginatingEndpoint = HeaderWriterAudit
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ReplyToAddress = HeaderWriterAudit
NServiceBus.TimeSent = 2026-04-29 22:10:59:617241 Z
NServiceBus.Version = 10.2.0
```

<!-- endsnippet -->

when that message fails to be processed, it will be sent to the error queue with the following headers:

<!-- snippet: HeaderWriterAuditAudit -->

```txt
$.diagnostics.hostdisplayname = MACHINENAME
$.diagnostics.hostid = daaf5ebc8d6a51b7b0dccdd8b15c3626
$.diagnostics.originating.hostid = daaf5ebc8d6a51b7b0dccdd8b15c3626
NServiceBus.ContentType = application/json
NServiceBus.ConversationId = 5520abbd-7b30-4914-a3d4-b43b016d917e
NServiceBus.CorrelationId = 4ad00d77-6e0d-44cc-bd3e-b43b016d917d
NServiceBus.EnclosedMessageTypes = Core.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = 4ad00d77-6e0d-44cc-bd3e-b43b016d917d
NServiceBus.MessageIntent = Send
NServiceBus.OpenTelemetry.StartNewTrace = False
NServiceBus.OriginatingEndpoint = HeaderWriterAudit
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ProcessingEnded = 2026-04-29 22:10:59:647662 Z
NServiceBus.ProcessingEndpoint = HeaderWriterAudit
NServiceBus.ProcessingMachine = MACHINENAME
NServiceBus.ProcessingStarted = 2026-04-29 22:10:59:639234 Z
NServiceBus.ReplyToAddress = HeaderWriterAudit
NServiceBus.TimeSent = 2026-04-29 22:10:59:617241 Z
NServiceBus.Version = 10.2.0
```

<!-- endsnippet -->


## Retries handling headers

Headers used to facilitate [retries](/nservicebus/recoverability/index.md).

> [!NOTE]
> These headers only exist after the first round of immediate reties has finished and are removed before sending a message to the error queue after all allowed retry attempts are exhausted.

### NServiceBus.Retries

The number of [delayed retries](/nservicebus/recoverability/index.md#delayed-retries) that have been performed for a message.

### NServiceBus.Retries.Timestamp

A timestamp used by [delayed retries](/nservicebus/recoverability/index.md#delayed-retries) to determine if the maximum time for retrying has been reached.

## Error forwarding headers

When a message exhausts the configured number of retry attempts and is moved to the error queue by the [recoverability](/nservicebus/recoverability/index.md) component, it will have the following extra headers added to the existing headers.

### NServiceBus.FailedQ

The queue at which the message processing failed.

### NServiceBus.ExceptionInfo.ExceptionType

The [Type.FullName](https://msdn.microsoft.com/en-us/library/system.type.fullname.aspx) of the Exception. It is obtained by calling `Exception.GetType().FullName`.

### NServiceBus.ExceptionInfo.InnerExceptionType

The full type name of the [InnerException](https://msdn.microsoft.com/en-us/library/system.exception.innerexception.aspx) if it exists. It is obtained by calling `Exception.InnerException.GetType().FullName`.

### NServiceBus.ExceptionInfo.HelpLink

The [exception help link](https://msdn.microsoft.com/en-us/library/system.exception.helplink.aspx).

### NServiceBus.ExceptionInfo.Message

The [exception message](https://msdn.microsoft.com/en-us/library/system.exception.message.aspx).

### NServiceBus.ExceptionInfo.Source

The [exception source](https://msdn.microsoft.com/en-us/library/system.exception.source.aspx).

### NServiceBus.ExceptionInfo.StackTrace

The [exception stack trace](https://msdn.microsoft.com/en-us/library/system.exception.stacktrace.aspx).

### Example error headers

Given an initiating message with the following headers:

<!-- snippet: HeaderWriterErrorSending -->

```txt
$.diagnostics.originating.hostid = daaf5ebc8d6a51b7b0dccdd8b15c3626
NServiceBus.ContentType = application/json
NServiceBus.ConversationId = be6afcc4-3295-4b6c-8d2f-b43b016c458b
NServiceBus.CorrelationId = eb8cf6f5-6817-4e9f-ba8e-b43b016c458a
NServiceBus.EnclosedMessageTypes = Core.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = eb8cf6f5-6817-4e9f-ba8e-b43b016c458a
NServiceBus.MessageIntent = Send
NServiceBus.OpenTelemetry.StartNewTrace = False
NServiceBus.OriginatingEndpoint = HeaderWriterError
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ReplyToAddress = HeaderWriterError
NServiceBus.TimeSent = 2026-04-29 22:06:16:354264 Z
NServiceBus.Version = 10.2.0
```

<!-- endsnippet -->

when that message fails to be processed, it will be sent to the error queue with the following headers:

<!-- snippet: HeaderWriterErrorError -->

```txt
$.diagnostics.hostdisplayname = MACHINENAME
$.diagnostics.hostid = daaf5ebc8d6a51b7b0dccdd8b15c3626
$.diagnostics.originating.hostid = daaf5ebc8d6a51b7b0dccdd8b15c3626
NServiceBus.ContentType = application/json
NServiceBus.ConversationId = be6afcc4-3295-4b6c-8d2f-b43b016c458b
NServiceBus.CorrelationId = eb8cf6f5-6817-4e9f-ba8e-b43b016c458a
NServiceBus.EnclosedMessageTypes = Core.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.ExceptionInfo.Data.Handler canceled = False
NServiceBus.ExceptionInfo.Data.Handler failure time = 2026-04-29 22:06:16:405692 Z
NServiceBus.ExceptionInfo.Data.Handler start time = 2026-04-29 22:06:16:405647 Z
NServiceBus.ExceptionInfo.Data.Handler type = Core.Headers.Writers.MyNamespace.MessageHandler
NServiceBus.ExceptionInfo.Data.Message ID = eb8cf6f5-6817-4e9f-ba8e-b43b016c458a
NServiceBus.ExceptionInfo.Data.Message type = Core.Headers.Writers.MyNamespace.MessageToSend
NServiceBus.ExceptionInfo.Data.Pipeline canceled = False
NServiceBus.ExceptionInfo.Data.Transport message ID = 737be1a4-a70c-4e9f-a5e7-c4d948f75a60
NServiceBus.ExceptionInfo.ExceptionType = System.Exception
NServiceBus.ExceptionInfo.Message = The exception message from the handler.
NServiceBus.ExceptionInfo.Source = Core_10
NServiceBus.ExceptionInfo.StackTrace = System.Exception: The exception message from the handler.
      at Core.Headers.Writers.HeaderWriterError.MessageHandler.Handle(MessageToSend message, IMessageHandlerContext context)
      at NServiceBus.InvokeHandlerTerminator.Terminate(IInvokeHandlerContext context)
      at NServiceBus.LoadHandlersConnector.Invoke(IIncomingLogicalMessageContext context, Func2 stage)
      at NServiceBus.LoadHandlersConnector.Invoke(IIncomingLogicalMessageContext context, Func2 stage)
      at NServiceBus.DeserializeMessageConnector.Invoke(IIncomingPhysicalMessageContext context, Func2 stage)
      at NServiceBus.ProcessingStatisticsBehavior.Invoke(IIncomingPhysicalMessageContext context, Func2 next)
      at NServiceBus.TransportReceiveToPhysicalMessageConnector.Invoke(ITransportReceiveContext context, Func2 next)
      at NServiceBus.TransportReceiveToPhysicalMessageConnector.Invoke(ITransportReceiveContext context, Func2 next)
      at NServiceBus.RetryAcknowledgementBehavior.Invoke(ITransportReceiveContext context, Func2 next)
      at NServiceBus.MainPipelineExecutor.Invoke(MessageContext messageContext, CancellationToken cancellationToken)
      at NServiceBus.MainPipelineExecutor.Invoke(MessageContext messageContext, CancellationToken cancellationToken)
      at NServiceBus.LogWrappedMessageReceiver.<>c__DisplayClass12_0.<<Initialize>g__ScopedOnMessage|0>d.MoveNext()
      at NServiceBus.LearningTransportMessagePump.ProcessFile(ILearningTransportTransaction transaction, String messageId, CancellationToken messageProcessingCancellationToken)
NServiceBus.FailedQ = HeaderWriterError
NServiceBus.MessageId = eb8cf6f5-6817-4e9f-ba8e-b43b016c458a
NServiceBus.MessageIntent = Send
NServiceBus.OpenTelemetry.StartNewTrace = False
NServiceBus.OriginatingEndpoint = HeaderWriterError
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ProcessingEndpoint = HeaderWriterError
NServiceBus.ProcessingMachine = MACHINENAME
NServiceBus.ReplyToAddress = HeaderWriterError
NServiceBus.TimeOfFailure = 2026-04-29 22:06:16:406166 Z
NServiceBus.TimeSent = 2026-04-29 22:06:16:354264 Z
NServiceBus.Version = 10.2.0
```

<!-- endsnippet -->

## Encryption headers

Headers when using [message property encryption](/nservicebus/security/property-encryption.md).

### NServiceBus.RijndaelKeyIdentifier

Identifies the encryption key used for encryption of the message property fragments.

#### Example headers

<!-- snippet: HeaderWriterEncryption -->

```txt
$.diagnostics.originating.hostid = daaf5ebc8d6a51b7b0dccdd8b15c3626
NServiceBus.ContentType = application/json
NServiceBus.ConversationId = 31e0cbc0-fcb9-4a9a-b0ab-b43b016dd62d
NServiceBus.CorrelationId = 1c474ad3-d00e-4477-9e49-b43b016dd62c
NServiceBus.EnclosedMessageTypes = Core.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = 1c474ad3-d00e-4477-9e49-b43b016dd62c
NServiceBus.MessageIntent = Send
NServiceBus.OpenTelemetry.StartNewTrace = False
NServiceBus.OriginatingEndpoint = HeaderWriterEncryption
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ReplyToAddress = HeaderWriterEncryption
NServiceBus.TimeSent = 2026-04-29 22:11:58:229357 Z
NServiceBus.Version = 10.2.0
```

<!-- endsnippet -->

#### Example body

<!-- snippet: HeaderWriterEncryptionBody -->

```txt
{"EncryptedProperty1":"String 1","EncryptedProperty2":"String 2"}
```

<!-- endsnippet -->

## File share data bus headers

When using the [file share data bus](/nservicebus/messaging/claimcheck/file-share.md), extra headers and serialized message information are necessary to correlate between the information on the queue and the data on the file system.

### Using DataBusProperty

When using the `DataBusProperty`, NServiceBus uses that property as a placeholder at serialization time. The serialized value of that property will contain a key. This key maps to a named header. That header then provides the path suffix of where that binary data is stored on disk on the file system.

The payload content-type is captured in the header `NServiceBus.DataBusConfig.ContentType`.

#### Example headers

<!-- snippet: HeaderWriterDataBusProperty -->

```txt
$.diagnostics.originating.hostid = daaf5ebc8d6a51b7b0dccdd8b15c3626
NServiceBus.ContentType = application/json
NServiceBus.ConversationId = 83247265-0cba-45c9-b987-b43b016d6444
NServiceBus.CorrelationId = df2e508a-671e-4439-8bc4-b43b016d6443
NServiceBus.DataBus.2026-04-29_22/b43dfae2-02b8-4e72-89a2-1281bfaded5b = 2026-04-29_22/b43dfae2-02b8-4e72-89a2-1281bfaded5b
NServiceBus.DataBus.2026-04-29_22/cd7802a5-dba4-43ed-9d8e-b5f6198560e9 = 2026-04-29_22/cd7802a5-dba4-43ed-9d8e-b5f6198560e9
NServiceBus.DataBusConfig.ContentType = application/json
NServiceBus.EnclosedMessageTypes = Core.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = df2e508a-671e-4439-8bc4-b43b016d6443
NServiceBus.MessageIntent = Send
NServiceBus.OpenTelemetry.StartNewTrace = False
NServiceBus.OriginatingEndpoint = HeaderWriterDataBusProperty
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ReplyToAddress = HeaderWriterDataBusProperty
NServiceBus.TimeSent = 2026-04-29 22:10:21:027928 Z
NServiceBus.Version = 10.2.0
```

<!-- endsnippet -->

#### Example body

<!-- snippet: HeaderWriterDataBusPropertyBody -->

```txt
{"LargeProperty1":{"Key":"2026-04-29_22/b43dfae2-02b8-4e72-89a2-1281bfaded5b","HasValue":true},"LargeProperty2":{"Key":"2026-04-29_22/cd7802a5-dba4-43ed-9d8e-b5f6198560e9","HasValue":true}}
```

<!-- endsnippet -->

### Using conventions

When using [conventions](/nservicebus/messaging/conventions.md) there is no way to store a correlation value inside the serialized property. Instead, each property has a matching header with the property name used as the header suffix. That header then provides the path suffix of where that binary data is stored on disk on the file system.

#### Example headers

<!-- snippet: HeaderWriterDataBusConvention -->

```txt
$.diagnostics.originating.hostid = daaf5ebc8d6a51b7b0dccdd8b15c3626
NServiceBus.ContentType = application/json
NServiceBus.ConversationId = ada01a9b-77b0-4163-99d2-b43b016b72f6
NServiceBus.CorrelationId = 1c907d5f-fafe-4898-857c-b43b016b72f5
NServiceBus.DataBus.Core.Headers.Writers.MyNamespace.MessageToSend.LargeProperty1 = 2026-04-29_22/eec27ca0-ef0e-41f3-aeb4-fb47057efb53
NServiceBus.DataBus.Core.Headers.Writers.MyNamespace.MessageToSend.LargeProperty2 = 2026-04-29_22/b32fc5cc-949a-4e62-87ec-8da83c644d3c
NServiceBus.DataBusConfig.ContentType = application/json
NServiceBus.EnclosedMessageTypes = Core.Headers.Writers.MyNamespace.MessageToSend, MyAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
NServiceBus.MessageId = 1c907d5f-fafe-4898-857c-b43b016b72f5
NServiceBus.MessageIntent = Send
NServiceBus.OpenTelemetry.StartNewTrace = False
NServiceBus.OriginatingEndpoint = HeaderWriterDataBusConvention
NServiceBus.OriginatingMachine = MACHINENAME
NServiceBus.ReplyToAddress = HeaderWriterDataBusConvention
NServiceBus.TimeSent = 2026-04-29 22:03:16:660116 Z
NServiceBus.Version = 10.2.0
```

<!-- endsnippet -->

#### Example body

<!-- snippet: HeaderWriterDataBusConventionBody -->

```txt
{"LargeProperty1":null,"LargeProperty2":null}
```

<!-- endsnippet -->

## ServiceControl

### ServiceControl.RetryTo

Value: Queue name

When present in a failed message to ServiceControl, ServiceControl will send the message to this queue instead of the queue name value from [NServiceBus.FailedQ](#error-forwarding-headers-nservicebus-failedq)

This is used by the ServiceControl transport adapter to bridge failed messages between different transports.

### ServiceControl.TargetEndpointAddress

Value: Queue name

Used by the [messaging bridge](/nservicebus/bridge/index.md) to return failed messages back to the correct queue

### ServiceControl.Retry.AcknowledgementQueue

Value: Queue name

The queue to send an acknowledgement system message back to a specific ServiceControl queue to mark a retried message as processed.

### ServiceControl.Retry.Successful

Contains a timestamp in the format `yyyy-MM-dd HH:mm:ss:ffffff Z` to indicate when a message was succesfully processed after a retry from ServiceControl.

Part of the control message sent to ServiceControl to signal that a message was manually retried in ServicePulse/Control and flagged as processed successfully.

### ServiceControl.Retry.UniqueMessageId

Contains the [NServiceBus.MessageId](#messaging-interaction-headers-nservicebus-messageid) value of the successfully processed message.

Part of the control message send back to ServiceControl to signal that a message that was manually retried in ServicePulse/Control and flagged as processed successfully.

The presence of any header key that starts with `ServiceControl.` indicates that the message has been retried from ServiceControl.