# IOutboxMessageSource

Package: [Microsoft.Orleans.Durable](/orleans/docs/api/csharp/microsoft.orleans.durable/) 10.0.0-alpha.1

[Source](https://github.com/dotnet/orleans/blob/6a0e937f544c35ffcf11b37e4c2b7de5a1580a03/src/Orleans.Durable/Messaging/IOutboxMessageSource.cs#L44)

```csharp
public interface IOutboxMessageSource
```

Provides outgoing messages whose payload and receiver the application stores in its own journaled state.

## Remarks

[IOutbox](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.ioutbox/) stages a reference entry which carries the message ID and delivery state, but no payload or receiver, so the payload is journaled once, in the application's state. The outbox keeps every delivery semantic of an ordinary message: delivery after the sending write is durable, retries with backoff, dead-lettering after `OutboxRetryTimeout`, wake-ups, and metrics.

The outbox calls [IOutboxMessageSource](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.ioutboxmessagesource/) when the message is sent and before every delivery attempt. The first registered source which returns the message owns it for the activation's lifetime; for an entry recovered from the journal, the first source which returns the message or throws owns it. When the entry retires, the outbox calls the owner's [IOutboxMessageSource](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.ioutboxmessagesource/) once for that entry in the current activation, synchronously, while it stages the entry's removal. The source's journaled changes and the removal commit in the same journal write. If the activation fails before that write commits, recovery restores the pending entry and the source's prior journaled state, and retiring the recovered entry invokes [IOutboxMessageSource](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.ioutboxmessagesource/) again.

A source withdraws a pending message through [IOutbox](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.ioutbox/), for example after the application times it out or an administrator removes it, and releases its payload in the same journal write. The outbox removes the entry without calling [IOutboxMessageSource](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.ioutboxmessagesource/) and makes no further delivery attempt. An attempt already in flight can still deliver the message and reads the buffers which [IOutboxMessageSource](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.ioutboxmessagesource/) returned, so keep them unchanged: release them by dropping references rather than reusing them.

A source which can't provide a pending message after its send, for example because its stored payload no longer decodes, throws from [IOutboxMessageSource](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.ioutboxmessagesource/); an invalid message is handled the same way. The outbox then dead-letters that entry alone, without delivering it, and calls [IOutboxMessageSource](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.ioutboxmessagesource/) with [DeadLettered](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.outboxmessageretirement.deadlettered/); the grain's messaging and its other messages are unaffected. A recovered entry which no registered source provides is dead-lettered the same way, without an owner to notify. Because no valid message exists, the dead letter's message carries only its [Envelope](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.envelope/), with an empty payload and a default [OutboxMessage](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.outboxmessage/), and its reason records the failure.

All calls run on the activation scheduler. Register sources during activation setup, before journal recovery: a recovered reference entry fails the activation when no source is registered. While a source provides a message, it returns the same message, envelope and receiver alike, for every call.

## Methods

- [OnRetired(MessageId, OutboxMessageRetirement)](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.ioutboxmessagesource/methods/onretired-orleans-durable-messaging-messageid-orleans-durable-messaging-outboxme-3e660e51/)
- [TryGetMessage(MessageId, OutboxMessage)](/orleans/docs/api/csharp/microsoft.orleans.durable/orleans.durable.messaging.ioutboxmessagesource/methods/trygetmessage-orleans-durable-messaging-messageid-out-orleans-durable-messaging-9cb53b68/)
