Mail

Output

The unread count for Apple Mail’s combined inbox, such as 3 unread. An inbox with no unread messages displays 0 unread; the item remains visible.

Failed reads never become a zero unread count. Successful readings include Inbox in the accessibility label, for example Inbox, 3 unread.

Example

{
  "schemaVersion": 1,
  "bar": {},
  "items": {
    "right": [
      {
        "id": "mail",
        "type": "mail",
        "primaryAction": { "kind": "application", "value": "com.apple.mail" }
      }
    ]
  }
}

This shows the unread count and opens Mail when clicked. The action is optional; monitoring itself never launches Mail.

Configuration

Use the item-level text template to customise or hide the label. The provider options below control its data, symbols, colours, and visibility.

There is no dedicated mail block. Use shared item options for styling, actions, visibility, and refresh policies.

An item-level symbol overrides both envelope symbols. It accepts an SF Symbol name or a font glyph object. Set symbolPosition to right to place it after the count; the default is left. Use style.tint for a fixed colour and style.minWidth to reserve space for changing counts.

Automation permission

Mail must already be running. When macOS requests permission to automate Mail, allow access in System Settings > Privacy & Security > Automation. Depending on how you launch sbar, macOS may attribute the request to the launching application. Check permission using the same launch method as your normal bar.

The sbar executable includes an Apple Events usage description. Custom builds must retain NSAppleEventsUsageDescription; without it, the provider reports Mail unavailable. Hardened-runtime builds also need the com.apple.security.automation.apple-events entitlement.

Text templates

The item-level text setting supports id, value, symbol, unreadCount, status, available. See text templates for syntax and field meanings. Use an available section with {{value}} as the fallback to preserve permission and read-error messages. Zero unread counts as present in sections.

Updates

The provider queries Mail immediately when enabled, then waits 30 seconds after each completed read before querying again. Failed reads retry on the same schedule. Apple Events run off the main thread with a ten-second timeout.

Monitoring is shared across items and displays. Default and event refresh follow completed readings. Interval and manual policies retain a snapshot until refreshed. A trigger captures the latest shared state; it does not force a new Mail query or change the polling interval. See refresh policies.

Current limits

Counts reflect Mail’s local synchronisation state. Only the combined inbox is supported, with no account or mailbox selection and no message content access. Other mail applications are not supported.

Use text for custom count labels. There are no dedicated state tints, symbol-visibility settings, or options to hide zero counts or error states.