Direct messages and the outbox

Guide index · Profiles and contacts

Queue encrypted content

Prerequisites: a running, authorized client, an established contact relationship, and the recipient's account ID. Keep the database and secret protector available for encryption, persistence, and pending-operation recovery.

public static async Task<MessageSendStatus> SendTextAsync(
    MeshlineClient client, string authorizedContactAccountId, string text,
    CancellationToken cancellationToken = default)
{
    var status = await client.MessageManager.SendMessageAsync(
        authorizedContactAccountId,
        new DirectMessageDraft
        {
            Body = new MessageBody { ContentType = "text/plain", Text = text }
        }, cancellationToken);
    Console.WriteLine($"{status.MessageId}: {status.State}");
    return status;
}

Source: Messaging.cs. SendMessageAsync queues a local outbox operation and returns MessageSendStatus. The running component submits pending messages. Retain the message ID to query GetSendStatusAsync and observe SendStatusChanged for progress.

Interpret send status

None and All are filter values, not additional progress stages. The SDK retries pending operations; an application should not turn an uncertain outcome into another SendMessageAsync call, which creates a separate outgoing message. CancelMessageAsync only changes a message while it is still Queued, returning false for missing messages and other states. Cancellation is not a remote recall of submitted or accepted content.

An outbox entry is removed after TargetAccepted. GetSendStatusAsync then returns null because no local outbox entry remains; null alone does not identify a delivery failure or prove delivery. Observe the status event and use stored messages for history rather than treating the outbox as a permanent delivery ledger.

public static async Task PrintPendingMessagesAsync(
    MeshlineClient client, CancellationToken cancellationToken = default)
{
    await using var reader = await client.MessageManager.GetOutboxAsync(
        state: MessageSendState.Queued | MessageSendState.Submitting | MessageSendState.SubmissionUnknown,
        cancellationToken: cancellationToken);
    while (true)
    {
        var batch = await reader.ReadNextAsync(50, cancellationToken);
        if (batch.Count == 0) break;
        foreach (var message in batch)
            Console.WriteLine($"{message.MessageId}: {message.State}");
    }
}

Receive and display messages

Subscribe to MessageReceived before starting synchronization when early arrivals matter. Notifications may contain multiple messages and run on background threads; dispatch UI changes to the application's UI thread. Use GetMessageAsync for a specific message or GetMessageHistoryAsync for persisted history. Event handling and durable local queries complement each other; rebuild the UI from storage after reopening the application.

Message bodies and attachments have protocol validation rules. text/plain is suitable for simple text; the application is responsible for rendering content safely. ContentReference describes externally stored content and its metadata. It does not make the SDK an attachment uploader or downloader.

Account messages are validated, deduplicated across relays, and stored in a local sequence. Contacts must be authorized at receive time. Storage or network failures should be diagnosed from the exposed errors while retaining pending state for retry.

API reference

MessageManager · DirectMessageDraft · MessageSendStatus · MessageSendState · MessageBody · ContentReference