Advanced Message Options

This page describes how to assign a unique ID to a message for tracking, apply custom tags, and control tracking settings on a per-message basis.

Maileroo Reference ID

Maileroo does not preserve the original Message-ID. Instead, you can use the X-Maileroo-Ref-ID header to assign a reference ID to a message for tracking and logging purposes.

The X-Maileroo-Ref-ID is a unique identifier automatically assigned to each message for tracking, identification, and logging purposes.

• It is always 24 characters long and only contains hexadecimal characters.
• It is usually generated using cryptographically secure random bytes encoded in hex.
• The Reference ID must remain unique for each message to avoid tracking conflicts.

You can provide your own Reference ID (optional) if it meets the 24-character length requirement; otherwise, the system will generate one for you automatically.

To assign a reference ID to a message, you can use the X-Maileroo-Ref-ID header in the message headers.

X-Maileroo-Ref-ID: my-unique-id

Generating a Reference ID

You can generate a unique Reference ID using a secure random string function (e.g., cryptographically strong random bytes encoded in Hex). Its length MUST ALWAYS be 24 characters.

PHP

$referenceId = bin2hex(random_bytes(12));
echo $referenceId;

Node.js

const crypto = require('crypto');
const referenceId = crypto.randomBytes(12).toString('hex');
console.log(referenceId);

Rust

use rand::RngCore;
use hex;

fn main() {
    let mut bytes = [0u8; 12];
    rand::thread_rng().fill_bytes(&mut bytes);
    let reference_id = hex::encode(bytes);
    println!("{}", reference_id);
}

Go

package main

import (
    "crypto/rand"
    "encoding/hex"
    "fmt"
)

func main() {
    bytes := make([]byte, 12)
    _, _ = rand.Read(bytes)
    referenceID := hex.EncodeToString(bytes)
    fmt.Println(referenceID)
}

Python

import secrets
reference_id = secrets.token_hex(12)
print(reference_id)

Ruby

require 'securerandom'
reference_id = SecureRandom.hex(12)
puts reference_id

Messaging Tagging

You can also add custom tags to your messages. This helps you track and aggregate emails by campaigns, users, or groups, and works great with webhooks for reporting and analytics.

To add tags to a message, you can use the X-Tag-* header in the message headers. Each tag is a key-value pair, where the key is the tag name and the value is the tag value.

The maximum length of a tag value is 768 characters.

Examples

X-Tag-user_id: 123
X-Tag-campaign_id: 456
X-Tag-email_type: welcome

Selective Open/Click Tracking

You can override the global open and click tracking settings for individual emails. To do this, include the following header in your message headers:

X-Maileroo-Track: yes|no

Examples

Tracking: Enabled

X-Maileroo-Track: yes

Tracking: Disabled

X-Maileroo-Track: no

The X-Maileroo-Track header is used to enable or disable open and click tracking for the email. The value must be either yes or no. If the header is not present, your account's settings will be used.