ReliableOutbox: persistent message queue with Telegram demo - library for MetaTrader 5

Why keep an uncertain result?

A missing response does not prove that a service missed a message. Telegram may accept a request while its reply is lost. Blindly retrying can therefore produce duplicates. ReliableOutbox is a small persistent MQL5 queue that makes this uncertainty visible instead of hiding it behind an automatic retry.

The queue commits IN_FLIGHT before calling its transport. A confirmed Telegram response produces SENT; an unprovable outcome produces UNCERTAIN, which is never resent automatically. Other eligible messages can still proceed. This is not guaranteed delivery or exactly-once delivery: a manual retry may duplicate a message, while discarding it may leave an undelivered message unsent.

Package and installation

The package contains six include files and two example Expert Advisors. OutboxTypes defines the states and transport contract; OutboxStore implements the two-slot checksummed store; Outbox owns queue transitions; SimTransport supplies offline scenarios; MiniJson validates JSON; TelegramTransport implements Bot API sendMessage. The queue itself contains no Telegram-specific response rules. No DLL, external library, private website or trading logic is required.

1. Download MQL5.zip, extract it, and copy its MQL5 folder into the terminal data folder opened through File > Open Data Folder. Keep the Experts/ReliableOutbox and Include/ReliableOutbox subfolders intact.
2. Compile ReliableOutboxDemo.mq5 and ReliableOutboxSelfTest.mq5 in MetaEditor. Both final examples compiled with zero errors and zero warnings.
3. Run SelfTest on a chart for the offline tests, or attach Demo in simulated mode. The symbol and timeframe do not matter; neither example trades.
4. For Telegram only, add https://api.telegram.org under Tools > Options > Expert Advisors > Allow WebRequest for listed URL. Never share a token-bearing request URL.

Demo inputs and controls

• Transport: simulated service by default; Telegram mode makes real sendMessage requests.
• Queue name: default demo; identifies the persistent queue. Simulation and Telegram use separate folders.
• Simulated service behaviour: default SIM_OK; selects offline acceptance, rejection, rate limiting, a request not started, or a processed request whose response is lost. Ignored in Telegram mode.
• Simulated mode: process one message per timer tick: default true; automatic processing applies only to simulation.
• Timer period, seconds: default 2; refreshes the display and schedules simulated processing.
• Telegram bot token: empty by default; enter a test bot token directly in terminal Inputs, not in source code or screenshots.
• Telegram chat id: empty by default; use the receiving chat's numeric id or an @channelusername, not the bot's own username. Start the bot conversation first and ensure it may post to the destination.
• Telegram request timeout, ms: default 10000; WebRequest is synchronous and blocks the EA until it finishes.

Enqueue adds a generated Demo message locally. Process attempts at most one eligible pending record. In Telegram mode only a Process click starts a request: attachment, restart and timer events never send automatically. The text counter is held in memory and is not the persistent queue ID displayed as #number.

Prev and Next select a record. Retry requires confirmation of duplicate risk for an uncertain record; cancelling does not resend it. Discard persists a local decision to stop sending, not a claim that the service never received it. Ack acknowledges an older-slot recovery condition; it does not bulk-authorize uncertain messages. Each uncertain record still needs its own decision.

States and transport results

• PENDING: waiting for its eligible send time.
• IN_FLIGHT: recorded before the request starts.
• SENT: confirmed acceptance by the service, not a recipient read receipt.
• REJECTED: explicit rejection with no automatic retry scheduled.
• UNCERTAIN: acceptance or rejection cannot be established; never automatically resent.
• DISCARDED: the user stopped local sending.

Telegram success requires complete valid JSON with ok=true and a valid sendMessage result for the configured chat. A complete Telegram rejection in a supported HTTP 4xx response is classified separately. A valid positive retry_after up to 2147483647 seconds is retained exactly; an unsupported larger delay is not shortened and is left for manual handling. Invalid or incomplete JSON/UTF-8, timeouts, connection failures and other unprovable results remain UNCERTAIN. An HTTP error alone is not proof of non-delivery.

A request classified as certainly not started uses a 60-second retry eligibility delay. In Telegram demo mode, becoming eligible still does not send anything without another Process click. See the transport source and the official Telegram Bot API documentation for the exact response checks.

Library use and limits

Supply an IOutboxTransport object to COutbox.Open, persist messages through Enqueue, and call ProcessOne with the current local time from your own scheduler. Keep the transport alive while the queue uses it. ItemAt and FindById expose read-only views. RetryManual requires the caller to obtain an explicit user decision; a local ID is not a Telegram idempotency key.

Only one instance may write a queue. A second chart opens it read-only and does not save, quarantine files or resolve messages. Reattach that instance to try acquiring the lock after the owner closes. Stored IN_FLIGHT records become UNCERTAIN on recovery, including a stop between the pre-send commit and the actual request. Corrupt or incomplete files are reported rather than silently treated as an empty successful queue.

A queue name is not bound to a bot or recipient: use a different name when changing either while messages remain pending or uncertain. Queued text is unencrypted, and the terminal may save credential inputs in profiles and templates. Use a disposable test bot and revoke its token after testing. Empty text and text beyond 4096 MQL5 string units are refused before enqueueing. WebRequest is unavailable in the Strategy Tester.

Tests and evidence

The final formatted build passed the existing 32-test offline suite: 23 queue tests and nine injected Telegram transport tests. The suite covers persistence and recovery, failed commits, locking/read-only behavior, per-message decisions, valid acceptance/rejection, retry delays, malformed responses, request encoding and UTF-8 validation. These responses are simulated or injected: no network request or real rate-limit flood is involved.

No new live Telegram message was sent during final formatting and packaging. Forced process termination, power loss and two terminals sharing one data folder were not tested; no resistance to those cases is claimed.

Offline self-test summary: 32 passed, 0 failed. Simulated and injected responses only; no network requests.