Publisher Specifications

October 9, 2025 ยท View on GitHub

Table of Contents

Content Format

Content Format V0

Note

For detailed instructions on encrypting the content format using the Double Ratchet algorithm, refer to the smswithoutborders_lib_sig documentation.

  1. Email format: from:to:cc:bcc:subject:body[:access_token:refresh_token]

    • Example: Gmail
    • Square brackets ([]) indicate optional fields.

  2. Text format: sender:text[:access_token:refresh_token]

    • Example: Twitter
    • Square brackets ([]) indicate optional fields.

  3. Message format: sender:receiver:message

    • Example: Telegram

  4. Test format: test_id

Content Format V1

Note

For detailed instructions on encrypting the content format using the Double Ratchet algorithm, refer to the smswithoutborders_lib_sig documentation.

Note

All service types use the same structure, but fields not applicable to a specific service type will have their length bytes set to 0, and no value bytes will follow for those fields.

All 2-byte length fields are encoded as unsigned little-endian.

  1. Email format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • 2 bytes: Length of to field.
    • 2 bytes: Length of cc field.
    • 2 bytes: Length of bcc field.
    • 1 byte: Length of subject field.
    • 2 bytes: Length of body field.
    • 1 byte: Length of access_token field (optional).
    • 1 byte: Length of refresh_token field (optional).
    • Variable: Value of from field.
    • Variable: Value of to field.
    • Variable: Value of cc field.
    • Variable: Value of bcc field.
    • Variable: Value of subject field.
    • Variable: Value of body field.
    • Variable: Value of access_token field (if present).
    • Variable: Value of refresh_token field (if present).

  2. Text format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • 2 bytes: Length of to field (set to 0).
    • 2 bytes: Length of cc field (set to 0).
    • 2 bytes: Length of bcc field (set to 0).
    • 1 byte: Length of subject field (set to 0).
    • 2 bytes: Length of body field.
    • 1 byte: Length of access_token field (optional).
    • 1 byte: Length of refresh_token field (optional).
    • Variable: Value of from field.
    • Variable: Value of body field.
    • Variable: Value of access_token field (if present).
    • Variable: Value of refresh_token field (if present).

  3. Message format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • 2 bytes: Length of to field.
    • 2 bytes: Length of cc field (set to 0).
    • 2 bytes: Length of bcc field (set to 0).
    • 1 byte: Length of subject field (set to 0).
    • 2 bytes: Length of body field.
    • 1 byte: Length of access_token field (set to 0).
    • 1 byte: Length of refresh_token field (set to 0).
    • Variable: Value of from field.
    • Variable: Value of to field.
    • Variable: Value of body field.

  4. Test format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • 2 bytes: Length of to field (set to 0).
    • 2 bytes: Length of cc field (set to 0).
    • 2 bytes: Length of bcc field (set to 0).
    • 1 byte: Length of subject field (set to 0).
    • 2 bytes: Length of body field (set to 0).
    • 1 byte: Length of access_token field (set to 0).
    • 1 byte: Length of refresh_token field (set to 0).
    • Variable: Value of from field (considered the test ID).

Content Format V2

Note

For detailed instructions on encrypting the content format using the Double Ratchet algorithm, refer to the smswithoutborders_lib_sig documentation.

Note

All service types use the same structure, but fields not applicable to a specific service type will have their length bytes set to 0, and no value bytes will follow for those fields.

All 2-byte length fields are encoded as unsigned little-endian.

  1. Email format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • 2 bytes: Length of to field.
    • 2 bytes: Length of cc field.
    • 2 bytes: Length of bcc field.
    • 1 byte: Length of subject field.
    • 2 bytes: Length of body field.
    • 2 bytes: Length of access_token field (optional).
    • 2 bytes: Length of refresh_token field (optional).
    • Variable: Value of from field.
    • Variable: Value of to field.
    • Variable: Value of cc field.
    • Variable: Value of bcc field.
    • Variable: Value of subject field.
    • Variable: Value of body field.
    • Variable: Value of access_token field (if present).
    • Variable: Value of refresh_token field (if present).

  2. Text format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • 2 bytes: Length of to field (set to 0).
    • 2 bytes: Length of cc field (set to 0).
    • 2 bytes: Length of bcc field (set to 0).
    • 1 byte: Length of subject field (set to 0).
    • 2 bytes: Length of body field.
    • 2 byte: Length of access_token field (optional).
    • 2 byte: Length of refresh_token field (optional).
    • Variable: Value of from field.
    • Variable: Value of body field.
    • Variable: Value of access_token field (if present).
    • Variable: Value of refresh_token field (if present).

  3. Message format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • 2 bytes: Length of to field.
    • 2 bytes: Length of cc field (set to 0).
    • 2 bytes: Length of bcc field (set to 0).
    • 1 byte: Length of subject field (set to 0).
    • 2 bytes: Length of body field.
    • 2 byte: Length of access_token field (set to 0).
    • 2 byte: Length of refresh_token field (set to 0).
    • Variable: Value of from field.
    • Variable: Value of to field.
    • Variable: Value of body field.

  4. Test format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • 2 bytes: Length of to field (set to 0).
    • 2 bytes: Length of cc field (set to 0).
    • 2 bytes: Length of bcc field (set to 0).
    • 1 byte: Length of subject field (set to 0).
    • 2 bytes: Length of body field (set to 0).
    • 2 byte: Length of access_token field (set to 0).
    • 2 byte: Length of refresh_token field (set to 0).
    • Variable: Value of from field (considered the test ID).

Content Format V3

Note

For detailed instructions on encrypting the content format using the Double Ratchet algorithm, refer to the smswithoutborders_lib_sig documentation.

Note

This format improves efficiency by only including length fields for applicable fields per service type, rather than including all fields with zero lengths.

All 2-byte length fields are encoded as unsigned little-endian.

  1. Email format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • 2 bytes: Length of to field.
    • 2 bytes: Length of cc field.
    • 2 bytes: Length of bcc field.
    • 1 byte: Length of subject field.
    • 2 bytes: Length of body field.
    • 2 bytes: Length of access_token field (optional).
    • 2 bytes: Length of refresh_token field (optional).
    • Variable: Value of from field.
    • Variable: Value of to field.
    • Variable: Value of cc field.
    • Variable: Value of bcc field.
    • Variable: Value of subject field.
    • Variable: Value of body field.
    • Variable: Value of access_token field (if present).
    • Variable: Value of refresh_token field (if present).

  2. Text format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • 2 bytes: Length of body field.
    • 2 bytes: Length of access_token field (optional).
    • 2 bytes: Length of refresh_token field (optional).
    • Variable: Value of from field.
    • Variable: Value of body field.
    • Variable: Value of access_token field (if present).
    • Variable: Value of refresh_token field (if present).

  3. Message format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • 2 bytes: Length of to field.
    • 2 bytes: Length of body field.
    • Variable: Value of from field.
    • Variable: Value of to field.
    • Variable: Value of body field.

  4. Test format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • Variable: Value of from field (considered the test ID).

Content Format V4

Note

For detailed instructions on encrypting the content format using the Double Ratchet algorithm, refer to the smswithoutborders_lib_sig documentation.

Note

This format extends V3 by adding support for image content.

All 2-byte length fields are encoded as unsigned little-endian.

  1. Email format: Binary-encoded fields with the following structure:

    • Variable: Value of image field.
    • 1 byte: Length of from field.
    • 2 bytes: Length of to field.
    • 2 bytes: Length of cc field.
    • 2 bytes: Length of bcc field.
    • 1 byte: Length of subject field.
    • 2 bytes: Length of body field.
    • 2 bytes: Length of access_token field (optional).
    • 2 bytes: Length of refresh_token field (optional).
    • Variable: Value of from field.
    • Variable: Value of to field.
    • Variable: Value of cc field.
    • Variable: Value of bcc field.
    • Variable: Value of subject field.
    • Variable: Value of body field.
    • Variable: Value of access_token field (if present).
    • Variable: Value of refresh_token field (if present).

  2. Text format: Binary-encoded fields with the following structure:

    • Variable: Value of image field.
    • 1 byte: Length of from field.
    • 2 bytes: Length of body field.
    • 2 bytes: Length of access_token field (optional).
    • 2 bytes: Length of refresh_token field (optional).
    • Variable: Value of from field.
    • Variable: Value of body field.
    • Variable: Value of access_token field (if present).
    • Variable: Value of refresh_token field (if present).

  3. Message format: Binary-encoded fields with the following structure:

    • Variable: Value of image field.
    • 1 byte: Length of from field.
    • 2 bytes: Length of to field.
    • 2 bytes: Length of body field.
    • Variable: Value of from field.
    • Variable: Value of to field.
    • Variable: Value of body field.

  4. Test format: Binary-encoded fields with the following structure:

    • 1 byte: Length of from field.
    • Variable: Value of from field (considered the test ID).

Supported Payload Versions

VersionHexadecimal ValueDecimal ValueDescription
v0NoneNoneLegacy format with 4-byte ciphertext length and no version marker. Device ID has variable length without explicit length field.
v10x011Introduces version marker, 2-byte ciphertext length, explicit device ID length field, and language code support. Uses Content Format V1 with 1-byte token length fields.
v20x022Same payload structure as V1 but uses Content Format V2 with 2-byte token length fields for better support of longer access/refresh tokens.
v30x033Same payload structure as V1/V2 but uses Content Format V3 with bitmap-based field presence indication for more efficient encoding.
v40x044Same payload structure as V1/V2/V3 but uses Content Format V4 with support for image content.

Payload Format V0

See available versions

Message Payload

  • Format:
    • 4 bytes: Ciphertext Length.
    • 1 byte: Platform shortcode. For a list of supported platforms and their corresponding shortcodes, refer to the Supported Platforms section.
    • Variable: Ciphertext. (encrypted Content Format V0).
    • Variable: Device ID.

Note

For detailed instructions on using the Double Ratchet algorithm to create ciphertext, refer to the smswithoutborders_lib_sig documentation.

Visual Representation:

+-------------------+--------------------+-------------------+-----------------+
| Ciphertext Length | Platform shortcode | Ciphertext        | Device ID       |
| (4 bytes)         | (1 byte)           | (Variable size)   | (Variable size) |
+-------------------+--------------------+-------------------+-----------------+

platform_shortcode = b'g'
encrypted_content = b'...'
device_id = b'...'

payload = struct.pack("<i", len(encrypted_content)) + platform_shortcode + encrypted_content + device_id
encoded = base64.b64encode(payload).decode("utf-8")
print(encoded)

Payload Format V1

See available versions

Message Payload

  • Format:
    • 1 byte: Version Marker. See available versions.
    • 2 bytes: Ciphertext Length.
    • 1 byte: Device ID Length.
    • 1 byte: Platform shortcode.
    • Variable: Ciphertext. (encrypted Content Format V1).
    • Variable: Device ID.
    • 2 bytes: Language Code (ISO 639-1 format).

Note

For detailed instructions on using the Double Ratchet algorithm to create ciphertext, refer to the smswithoutborders_lib_sig documentation.

Visual Representation:

+----------------+-------------------+------------------+--------------------+-----------------+-----------------+---------------+
| Version Marker | Ciphertext Length | Device ID Length | Platform shortcode | Ciphertext      | Device ID       | Language Code |
| (1 byte)       | (2 bytes)         | (1 byte)         | (1 byte)           | (Variable size) | (Variable size) | (2 bytes)     |
+----------------+-------------------+------------------+--------------------+-----------------+-----------------+---------------+

version_marker = b'\x01'
platform_shortcode = b'g'
language_code = b'en'
device_id = b'...'
encrypted_content = b'...'

payload = (
   version_marker +
   struct.pack("<H", len(encrypted_content)) +
   bytes([len(device_id)]) +
   platform_shortcode +
   encrypted_content +
   device_id +
   language_code
)
encoded = base64.b64encode(payload).decode("utf-8")
print(encoded)

Payload Format V2

See available versions

Message Payload

  • Format:
    • 1 byte: Version Marker. See available versions.
    • 2 bytes: Ciphertext Length.
    • 1 byte: Device ID Length.
    • 1 byte: Platform shortcode.
    • Variable: Ciphertext. (encrypted Content Format V2).
    • Variable: Device ID.
    • 2 bytes: Language Code (ISO 639-1 format).

Note

For detailed instructions on using the Double Ratchet algorithm to create ciphertext, refer to the smswithoutborders_lib_sig documentation.

Visual Representation:

+----------------+-------------------+------------------+--------------------+-----------------+-----------------+---------------+
| Version Marker | Ciphertext Length | Device ID Length | Platform shortcode | Ciphertext      | Device ID       | Language Code |
| (1 byte)       | (2 bytes)         | (1 byte)         | (1 byte)           | (Variable size) | (Variable size) | (2 bytes)     |
+----------------+-------------------+------------------+--------------------+-----------------+-----------------+---------------+

version_marker = b'\x02'
platform_shortcode = b'g'
language_code = b'en'
device_id = b'...'
encrypted_content = b'...'

payload = (
   version_marker +
   struct.pack("<H", len(encrypted_content)) +
   bytes([len(device_id)]) +
   platform_shortcode +
   encrypted_content +
   device_id +
   language_code
)
encoded = base64.b64encode(payload).decode("utf-8")
print(encoded)

Payload Format V3

See available versions

Message Payload

  • Format:
    • 1 byte: Version Marker. See available versions.
    • 2 bytes: Ciphertext Length.
    • 1 byte: Device ID Length.
    • 1 byte: Platform shortcode.
    • Variable: Ciphertext. (encrypted Content Format V3).
    • Variable: Device ID.
    • 2 bytes: Language Code (ISO 639-1 format).

Note

For detailed instructions on using the Double Ratchet algorithm to create ciphertext, refer to the smswithoutborders_lib_sig documentation.

Visual Representation:

+----------------+-------------------+------------------+--------------------+-----------------+-----------------+---------------+
| Version Marker | Ciphertext Length | Device ID Length | Platform shortcode | Ciphertext      | Device ID       | Language Code |
| (1 byte)       | (2 bytes)         | (1 byte)         | (1 byte)           | (Variable size) | (Variable size) | (2 bytes)     |
+----------------+-------------------+------------------+--------------------+-----------------+-----------------+---------------+

version_marker = b'\x03'
platform_shortcode = b'g'
language_code = b'en'
device_id = b'...'
encrypted_content = b'...'

payload = (
   version_marker +
   struct.pack("<H", len(encrypted_content)) +
   bytes([len(device_id)]) +
   platform_shortcode +
   encrypted_content +
   device_id +
   language_code
)
encoded = base64.b64encode(payload).decode("utf-8")
print(encoded)

Payload Format V4

See available versions

Message Payload

  • Format:
    • 1 byte: Version Marker. See available versions.
    • 2 bytes: Ciphertext Length.
    • 1 byte: Device ID Length.
    • 1 byte: Platform shortcode.
    • Variable: Ciphertext. (encrypted Content Format V4).
    • Variable: Device ID.
    • 2 bytes: Language Code (ISO 639-1 format).

Note

For detailed instructions on using the Double Ratchet algorithm to create ciphertext, refer to the smswithoutborders_lib_sig documentation.

Visual Representation:

+----------------+-------------------+------------------+--------------------+-----------------+-----------------+---------------+
| Version Marker | Ciphertext Length | Device ID Length | Platform shortcode | Ciphertext      | Device ID       | Language Code |
| (1 byte)       | (2 bytes)         | (1 byte)         | (1 byte)           | (Variable size) | (Variable size) | (2 bytes)     |
+----------------+-------------------+------------------+--------------------+-----------------+-----------------+---------------+

version_marker = b'\x04'
platform_shortcode = b'g'
language_code = b'en'
device_id = b'...'
encrypted_content = b'...'

payload = (
   version_marker +
   struct.pack("<H", len(encrypted_content)) +
   bytes([len(device_id)]) +
   platform_shortcode +
   encrypted_content +
   device_id +
   language_code
)
encoded = base64.b64encode(payload).decode("utf-8")
print(encoded)