Message Format Reference

Common rules

Message

Size limits

Field "keySafe"

Parameters
  • msgFormat (uint32)
  • symmCipher (string)
  • symmKey (string)
  • hashAlgo (string)

msgFormat is fixed to 1. symmCipher is fixed for msgFormat == 1. symmKey is a base64-encoded random symmetric key. It must be usable for the algorithm given in symmCipher. It must not be reused for multiple messages or even for multiple copies of the same message. hashAlgo is fixed for msgFormat == 1.

Example:

{
    "msgFormat": 1,
    "symmCipher": "AES-256/GCM",
    "symmKey": "...",
    "hashAlgo": "SHA-512"
}

Format

Field "content"

{
    "sender": {
        "name": "John Doe",
        "address": "john.doe#kullo.net",
        "organization": "Doe Corp.",         // optional, default: ""
        "avatar": {                          // optional, default: {}
            "mimeType": "...",               // "image/png" or "image/jpeg"
            "data": "..."                    // base64-encoded image file
                                             // max. resolution: 200x200 px
        }
    },
    "recipients": [
        "alice#kullo.net",
        "bob#kullo.net"
    ],
    "dateSent": "2013-11-04T16:19:31+01:00",
    "text": "Here comes the message text.",  // optional, default: ""
    "footer": "Here comes the footer.",      // optional, default: ""
    "attachmentsIndex": [                    // optional, default: []
        {
            "filename": "my_first_file.pdf",
            "mimeType": "application/pdf",
            "note": "First file",            // optional, default: ""
            "size": 123456,
            "hash": "..."                    // SHA-512 of file content, hex format
        },
        {
            "filename": "my second file.jpg",
            "mimeType": "application/jpeg",
            "note": "Last file",
            "size": 1234567,
            "hash": "..."
        }
    }
}

Format

Field "attachments"

The attachments field contains all attachments as one binary block.

Format

Attention! If the message doesn't contain any attachments, or if it does only contain zero-length attachments, the attachments field must be empty. However, there are old versions of the client software that uploaded invalid attachment records for messages without non-empty attachments. To cope with that, simply don't try to download and parse them if a message doesn't have non-empty attachments.

If there is at least one non-empty attachment, the following format is used:

Field "meta"

{
    "read": 1,
    "done": 0
}

Note that we use 0 and 1, not false and true. The reason is that true has a different length than false, so that the values of read and done could be inferred by looking at the length of the ciphertext.

Format