Query 1: Last Week's Unread Email#

Use Case Description#

Retrieve all unread emails from the past 7 days, sorted by received date (newest first). This is one of the most common email queries - getting up to date with recent unread messages.

Key JMAP Concepts Used#

• Email/query: Filtering emails by keywords and date ranges
• Filter conditions: Using hasKeyword (negated) and after date filtering
• Sorting: By receivedAt in descending order
• Property selection: Requesting common display properties for efficiency

JMAP Request#

{
  "using": ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"],
  "methodCalls": [
    [
      "Email/query",
      {
        "accountId": "u12345678",
        "filter": {
          "operator": "AND",
          "conditions": [
            {
              "hasKeyword": "$seen",
              "value": false
            },
            {
              "after": "2024-08-18T00:00:00Z"
            }
          ]
        },
        "sort": [
          {
            "property": "receivedAt",
            "isAscending": false
          }
        ],
        "limit": 50
      },
      "q0"
    ],
    [
      "Email/get",
      {
        "accountId": "u12345678",
        "#ids": {
          "resultOf": "q0",
          "name": "Email/query",
          "path": "/ids"
        },
        "properties": [
          "id", "threadId", "mailboxIds", "keywords", "from", "to", "cc",
          "subject", "receivedAt", "hasAttachment", "preview", "size"
        ]
      },
      "g0"
    ]
  ]
}

Expected Response Structure#

{
  "methodResponses": [
    [
      "Email/query",
      {
        "accountId": "u12345678",
        "queryState": "q1234567890",
        "canCalculateChanges": true,
        "position": 0,
        "ids": ["Memail123", "Memail124", "Memail125"],
        "total": 47,
        "limit": 50
      },
      "q0"
    ],
    [
      "Email/get",
      {
        "accountId": "u12345678",
        "state": "s9876543210",
        "list": [
          {
            "id": "Memail123",
            "threadId": "Tthread456",
            "mailboxIds": {"Minbox": true},
            "keywords": {},
            "from": [{"email": "alice@example.com", "name": "Alice Smith"}],
            "to": [{"email": "me@example.com", "name": "John Doe"}],
            "subject": "Re: Project Update",
            "receivedAt": "2024-08-24T14:30:00Z",
            "hasAttachment": false,
            "preview": "Thanks for the update. I've reviewed the documents and...",
            "size": 2543
          }
        ],
        "notFound": []
      },
      "g0"
    ]
  ]
}

Explanation of Key Features#

Filter Logic#

• hasKeyword: "$seen", value: false - Find emails that do NOT have the $seen keyword (unread emails)
• after: "2024-08-18T00:00:00Z" - Only emails received after 7 days ago
• operator: "AND" - Both conditions must be satisfied

Result References#

• #ids with resultOf - Passes the list of email IDs from the query directly to Email/get
• This avoids duplicating IDs in the request and ensures consistency

Property Selection#

• Includes essential display properties while excluding heavy content like bodyStructure and bodyValues
• preview gives a text snippet for quick scanning
• hasAttachment allows UI indicators for attachments

Sorting and Pagination#

• sort by receivedAt descending shows newest emails first
• limit: 50 prevents overwhelming responses while handling most inbox scenarios
• total in response shows how many unread emails exist overall