Query 2: Apple Mail Orange Flagged Messages#

Use Case Description#

Find the oldest message marked with Apple Mail's orange flag. Apple Mail uses a bit flag system where orange flags correspond to $MailFlagBit1 keyword. This query demonstrates vendor-specific keyword handling and oldest-first sorting.

Key JMAP Concepts Used#

• Apple Mail Extensions: Using $MailFlagBit1 keyword for orange flag
• Vendor-specific keywords: Handling Apple Mail's color flag system
• Ascending sort: Finding oldest messages first
• Single result limiting: Using limit: 1 to get just the oldest

JMAP Request#

{
  "using": ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"],
  "methodCalls": [
    [
      "Email/query",
      {
        "accountId": "u12345678",
        "filter": {
          "hasKeyword": "$MailFlagBit1"
        },
        "sort": [
          {
            "property": "receivedAt",
            "isAscending": true
          }
        ],
        "limit": 1
      },
      "q0"
    ],
    [
      "Email/get",
      {
        "accountId": "u12345678",
        "#ids": {
          "resultOf": "q0",
          "name": "Email/query",
          "path": "/ids"
        },
        "properties": [
          "id", "threadId", "mailboxIds", "keywords", "from", "subject", 
          "receivedAt", "sentAt", "preview", "textBody", "hasAttachment"
        ]
      },
      "g0"
    ]
  ]
}

Expected Response Structure#

{
  "methodResponses": [
    [
      "Email/query",
      {
        "accountId": "u12345678",
        "queryState": "q1234567891",
        "canCalculateChanges": true,
        "position": 0,
        "ids": ["Memail456"],
        "total": 1,
        "limit": 1
      },
      "q0"
    ],
    [
      "Email/get", 
      {
        "accountId": "u12345678",
        "state": "s9876543211",
        "list": [
          {
            "id": "Memail456",
            "threadId": "Tthread789",
            "mailboxIds": {"Mimportant": true, "Minbox": true},
            "keywords": {
              "$MailFlagBit1": true,
              "$flagged": true
            },
            "from": [{"email": "boss@company.com", "name": "Jane Manager"}],
            "subject": "Q4 Budget Review - Action Required",
            "receivedAt": "2024-07-15T09:30:00Z",
            "sentAt": "2024-07-15T09:28:00Z", 
            "preview": "Please review the attached Q4 budget proposal and provide feedback by Friday...",
            "textBody": [
              {
                "id": "text1",
                "mimeType": "text/plain",
                "size": 1542
              }
            ],
            "hasAttachment": true
          }
        ],
        "notFound": []
      },
      "g0"
    ]
  ]
}

Explanation of Key Features#

Apple Mail Color Flags#

Apple Mail uses a bit flag system for color categorization:

• $MailFlagBit0 - Red flag
• $MailFlagBit1 - Orange flag
• $MailFlagBit2 - Yellow flag
• Combinations create other colors (e.g., red+yellow = green)

Vendor Keyword Extensions#

• JMAP supports custom keywords with $ prefix for system/vendor keywords
• Apple Mail specific keywords are preserved during sync
• Other clients may display these as generic flags or ignore them

Oldest-First Search Pattern#

• isAscending: true on receivedAt sorts chronologically
• limit: 1 efficiently returns just the oldest match
• Useful for finding forgotten important items or ancient flagged emails

Enhanced Property Set#

• textBody provides access to plain text content structure
• Both sentAt and receivedAt show email timing
• keywords object shows all applied flags and keywords

Business Logic Applications#

This pattern is useful for:

• Finding long-overdue flagged action items
• Auditing old important emails
• Cleaning up stale flags and categories
• Understanding email aging patterns