Sync changes

The call to make when a client comes back, instead of fetching the mailbox again. Over a mobile connection the difference between four rows and two hundred is the difference between an app that opens and one that spins.

Two halves, because a cache can be wrong in two ways. Something changed, which is an ordinary row. Or something disappeared, which is an absence and can never turn up in a list of rows.

Request

curl "https://api.proppertrading.com/v1/me/mail/changes?since=2026-08-19T12:00:00Z&limit=50" \
  -H "Authorization: Bearer ptat_9f2c1a44_3b8e7d2f5c9a1b4e6d8f0a2c4e6b8d1f"

Response

{
    "data": {
        "object": "mail_changes",
        "updated": [
            {
                "object": "mail_message",
                "id": "msg_h3k8q2w7n4r9t5vx",
                "folder": "trash",
                "is_read": true
            }
        ],
        "deleted": ["msg_x2m7k4q9w3n8t5vd"],
        "has_more": true,
        "next_since": "MjAyNi0wOC0xOSAxODoyMDo0Ni4wMDAwMDB8bXNnX2gzazhxMnc3bjRyOXQ1dng"
    },
    "meta": { "request_id": "req_01kz4bkr1aj1gv63d8fv3133ey" }
}

Walking it

Oldest change first, so a client that gets halfway and loses signal resumes exactly where it stopped rather than starting over. Keep calling while has_more is true, then store next_since until the next time.

next_since is a position, not a clock reading. It carries the id of the last message as well as the timestamp, so two messages that changed in the same second cannot straddle a page boundary and have one of them skipped.

deleted is not paged. Bare ids are small, and a client with more deletions than fit in one response has a much worse problem than the size of it.

When a client has been away too long

Deletion records are kept for 45 days. A since older than that answers sync_window_expired, because past that point we cannot promise the list of deletions is complete, and a sync that quietly misses things is worse than being told to start over. Fetch the message list again and begin a fresh sync from now.

A cache from before 2026-10-08

Messages were named by numbers until then, and a next_since from that time carries one. It answers invalid_since. Every id in a cache built before then is a number that names nothing any more, so do the same as above: fetch the message list again and begin a fresh sync from now. Messages erased before the change are not in deleted, because they were never recorded under their new id.

Errors