MX API Mail

POST

/mail/sync

Sync

Sync a mailbox incrementally using MODSEQ or UID fallback.

Request

{
  "mailbox": "INBOX",
  "uidvalidity": "33",
  "token": "4400"
}

curl -X POST "http://127.0.0.1:3000/mail/sync" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"mailbox":"INBOX","token":"4400"}'

Response

{
  "mailbox": "INBOX",
  "uidvalidity": "33",
  "token": "4401",
  "changes": {
    "added": [{ "uid": 120 }],
    "updated": [{ "uid": 119, "modseq": "4401", "flags": ["\\\\Seen"] }],
    "removed": [{ "uid": 80 }]
  }
}

GET

/mail/message

Message

Fetch a full message including RFC822 source and body structure.

Request

Query: mailbox, uid

curl -X GET "http://127.0.0.1:3000/mail/message?mailbox=INBOX&uid=120" \
  -H "Authorization: Bearer YOUR_JWT"

Response

{
  "uid": 120,
  "envelope": { "subject": "Welcome" },
  "flags": ["\\\\Seen"],
  "rfc822": "raw message source",
  "bodyStructure": {}
}

GET

/mail/attachment

Attachment

Stream a specific MIME part as binary data.

Request

Query: mailbox, uid, part

curl -X GET "http://127.0.0.1:3000/mail/attachment?mailbox=INBOX&uid=120&part=2.1" \
  -H "Authorization: Bearer YOUR_JWT" \
  -o attachment.bin

Response

Content-Type: application/octet-stream

WS

/ws

Realtime

Connect to receive mailbox change events in realtime.

Connect

wscat -c "ws://127.0.0.1:3000/ws" \
  -H "Authorization: Bearer YOUR_JWT"

The server sends a hello message after connecting.

Event payload

{
  "type": "mailbox_changed",
  "mailbox": "INBOX",
  "uidvalidity": "33",
  "token": "4401",
  "eventType": "MailboxesChanged"
}