Mailboxes function similarly to queues, facilitating data exchange between tasks based on a First In, First Out (FIFO) discipline. The primary distinction between a mailbox and a queue is that a mailbox does not impose fixed limits on message size or the number of messages; capacity is governed solely by available system memory. Consequently, mailboxes are ideally suited for exchanging large or variable-sized data sets.

The osCreateMailbox function is used to initialize a mailbox object. A mailbox may be created during system initialization, within an interrupt service routine (ISR), or by a running task. During creation, an optional name may be assigned to the mailbox, allowing other tasks to obtain a handle via the osOpenMailbox function. These functions return a system-assigned handle used to identify the object in subsequent operations. When a mailbox is no longer required, it must be closed using osCloseHandle. The mailbox is permanently deleted only after all tasks that opened the handle have closed it. For further details, refer to the system objects management section.

If mailbox functionality is not required by the application, the OS_USE_MAILBOX constant can be set to 0 to reduce the memory footprint of the output code.

The maximum number of messages and their respective sizes are not pre-defined for mailboxes. Unless direct read-write mode is active, posting a message triggers a dynamic memory allocation where the message data is stored. This memory block is automatically freed when the message is read, or if the mailbox is cleared or deleted.

To post a message to the mailbox, use the osMailboxPost function. The osMailboxPend function retrieves and removes the first message from the mailbox. To retrieve a message without removing it from the buffer, use the osMailboxPeek function. Additionally, standard system I/O functions such as osRead and osWrite may be utilized. To discard all pending messages, call the osClearMailbox function.

The osGetMailboxInfo function, available when OS_MBOX_GET_INFO_FUNC is set to 1, provides telemetry regarding the total number of queued messages and the size of the message currently at the head of the mailbox.

If OS_MBOX_PEEK_FUNC is enabled, mailbox access during data copy operations must be synchronized. Synchronization can be implemented in three ways: via a mutex, an auto-reset event, or by temporarily disabling interrupts. Interrupt disabling is recommended only for small data transfers. The synchronization method is selected at creation using the OS_IPC_PROTECT_MUTEX, OS_IPC_PROTECT_EVENT, or OS_IPC_PROTECT_INT_CTRL flags. Synchronization via mutex or event is only available if the corresponding OS_MBOX_PROTECT_MUTEX or OS_MBOX_PROTECT_EVENT constants are set to 1. If osTerminateTask is utilized on tasks performing mailbox operations, mutex-based synchronization is strongly advised.

Attempting to read from an empty mailbox results in an error unless the OS_IPC_WAIT_IF_EMPTY flag was specified during creation. If enabled, the task will block until data is posted or a timeout occurs. This feature is available only when OS_MBOX_ALLOW_WAIT_IF_EMPTY is set to 1.

When blocking is enabled, data can be transferred directly between tasks without intermediate storage in the mailbox. This optimization is enabled via the OS_IPC_DIRECT_READ_WRITE mode flag and is available only when OS_MBOX_ALLOW_DIRECT_RW is set to 1.