Kerzo Postal Suite Public API

Technical documentation for World of Warcraft addon developers. Integrate themes and skin adapters into Kerzo Postal Suite (KPS) with Zero-Taint execution, callback sandboxing, and settings synchronization.

Global Namespaces

The KPS Public API is accessible through the global entry point:

_G.KerzoPostalSuiteAPI • KPE.API (internal)

All external callbacks and theme hooks are strictly sandboxed inside protective pcall wrappers. Third-party theme errors will never break the mail interface or taint secure execution paths.

1. Technical Architecture & Zero-Taint Sandbox

Kerzo Postal Suite implements an isolated, event-driven theme engine designed to operate safely across Retail, WoW Forever, and Classic clients:

Principle	Implementation Detail	Addon Developer Guarantee
Zero Taint Propagation	All external callbacks (`onApply`, `onRemove`, `name()`, and event listeners) execute encapsulated inside `pcall` blocks.	Runtime errors in third-party addons will not trigger Blizzard ActionBlocked UI taint errors.
Protected Base Themes	Built-in system themes (`classic`, `light`, `contrast`, `dark`, `ellesmere`) cannot be overwritten or unregistered.	Core presets remain intact and serve as safe fallbacks if an external theme is removed.
Zero CPU Idle	Event-driven reactive pipeline without permanent `OnUpdate` polling scripts.	0.00ms CPU footprint when idle, meeting the Kerzo Suite performance protocol.
Dynamic Theme Synchronization	Themes registered via `RegisterTheme` are automatically added to the valid theme catalog and refresh the settings drawer.	Immediate availability in the KPS settings UI without modifying KPS source code.

2. Multi-Client & 10 Blizzard Locales

Kerzo Postal Suite (v4.0.0+) operates seamlessly across all active World of Warcraft branches and language clients:

Certified Multi-Client Matrix

WoW Retail (12.x Midnight): Full native support (120105, 120107).
WoW Forever (1.60.x): Full native support (16001).
WoW Classic Era, TBC Anniversary & Classic Progression: Full compatibility (11509, 20506, 50504).
10 Official Languages (12 Locales): enUS, enGB, esES, esMX, deDE, frFR, itIT, ptBR, ruRU, koKR, zhCN, zhTW.

3. Theme & Skin Methods

THEME KerzoPostalSuiteAPI:RegisterTheme(themeID, themeData)

▼

Registers a custom visual theme into Kerzo Postal Suite. The theme is immediately added to the valid theme catalog, refreshes the settings drawer, and emits an OnThemeRegistered event. If the registered themeID matches the user's currently saved theme, it is applied automatically.

Parameters

themeID string, required Unique non-empty identifier for the theme (e.g. "nordic_dark", "elvui_clean"). Cannot match built-in base themes (classic, light, contrast, dark, ellesmere).
themeData table, required
Table containing metadata and lifecycle callbacks for the theme:
- name (string|function, required): Display name shown in the theme selector.
- onApply (function, required): Callback invoked when the theme is activated: function(kpe).
- onRemove (function, optional): Callback invoked when switching away from this theme or unregistering it while active: function(kpe).
- palette (table, optional): Custom color/texture palette table returned by kpe:ObtenerPaletaTema(themeID). Falls back to the classic palette if omitted.
- author (string, optional): Author or UI suite name.
- description (string, optional): Short description.

Returns

boolean success, string? errorMessage

Example

Lua: Register Custom Theme

local API = _G.KerzoPostalSuiteAPI
if not API then return end

API:RegisterTheme("nordic_dark", {
    name = "Nordic Dark",
    author = "Community",
    description = "Minimalist slate-grey appearance for Kerzo Postal Suite.",
    onApply = function(kpe)
        if kpe.GestorTemas then
            local frames = kpe.GestorTemas:ObtenerMarcosRegistrados()
            for _, entry in pairs(frames) do
                if entry.marco and entry.marco.NineSlice then
                    entry.marco.NineSlice:SetAlpha(0)
                end
            end
        end
    end,
    onRemove = function(kpe)
        if kpe.GestorTemas then
            local frames = kpe.GestorTemas:ObtenerMarcosRegistrados()
            for _, entry in pairs(frames) do
                if entry.marco then
                    kpe:RestaurarRegionesMarco(entry.marco)
                end
            end
        end
    end,
})

THEME KerzoPostalSuiteAPI:UnregisterTheme(themeID)

▼

Unregisters an external theme. Built-in base themes cannot be removed. If the theme is currently active, KPS invokes onRemove(kpe), falls back to "classic", emits OnThemeUnregistered, and refreshes the settings drawer.

Parameters

themeID string, required Identifier of the external theme to remove.

Returns

boolean success, string? errorMessage

THEME KerzoPostalSuiteAPI:ApplyTheme(themeID)

▼

Programmatically activates a built-in or registered external theme, persists the choice, emits OnThemeChanged, and refreshes the settings drawer.

Parameters

themeID string, required Valid theme identifier (built-in or registered via RegisterTheme).

Returns

boolean success, string? errorMessage

QUERY KerzoPostalSuiteAPI:GetCurrentTheme()

▼

Returns the identifier of the currently active visual theme in Kerzo Postal Suite (defaults to "classic").

Returns

string themeID

QUERY KerzoPostalSuiteAPI:GetRegisteredThemes()

▼

Returns a shallow copy table of all external themes currently registered through the Public API. Dynamic name functions are evaluated safely inside pcall.

Returns

table<string, { id: string, name: string, author: string?, description: string? }>

4. Control & Lifecycle

EVENT KerzoPostalSuiteAPI:RegisterCallback(eventName, callbackFunc)

▼

Subscribes a listener function to a KPS theme lifecycle event. All registered callbacks execute inside protective pcall wrappers.

Parameters

eventName string, required One of: "OnThemeChanged", "OnThemeRegistered", "OnThemeUnregistered", "OnThemeApplied".
callbackFunc function, required Function invoked when the event fires.

Returns

boolean success, string? errorMessage

5. External Skin Creation Guide (Community Skins & UI Suites)

Kerzo Postal Suite exposes an open, decoupled skinning engine. External addons and UI suites can register custom palettes and frame stylings cleanly while preserving full mail functionality.

Lua: Skin Registration Pattern with Palette

local API = _G.KerzoPostalSuiteAPI
if not API then return end

API:RegisterTheme("custom_suite", {
    name = "Custom UI Suite",
    author = "Community Developer",
    description = "Flat dark skin with custom accent borders.",
    palette = {
        esOscuro = true,
        fondoOscuroTexto = true,
        usarPergamino = false,
        fondoVentana = { 0.06, 0.06, 0.07, 0.97 },
        bordeVentana = { 0.25, 0.25, 0.28, 1.0 },
        textoTituloClaro = { 0.95, 0.95, 0.98, 1.0 },
    },
    onApply = function(kpe)
        -- Customize registered KPS frames when theme is applied
        if kpe.GestorTemas then
            for _, registro in pairs(kpe.GestorTemas:ObtenerMarcosRegistrados()) do
                if registro.marco and registro.marco.NineSlice then
                    registro.marco.NineSlice:SetAlpha(0)
                end
            end
        end
    end,
    onRemove = function(kpe)
        -- Restore default frame regions when switching away
        if kpe.GestorTemas and kpe.RestaurarRegionesMarco then
            for _, registro in pairs(kpe.GestorTemas:ObtenerMarcosRegistrados()) do
                if registro.marco then
                    kpe:RestaurarRegionesMarco(registro.marco)
                end
            end
        end
    end,
})

6. Lifecycle Events Reference

Event Name	Payload Arguments	Trigger Description
`OnThemeChanged`	`(themeID)`	Fired when the active theme is changed via `ApplyTheme(themeID)`.
`OnThemeRegistered`	`(themeID, themeData)`	Fired when a new external theme is registered via `RegisterTheme`.
`OnThemeUnregistered`	`(themeID)`	Fired when an external theme is removed via `UnregisterTheme`.
`OnThemeApplied`	`(themeID)`	Fired whenever `AplicarTemaGlobal()` finishes applying a theme across registered frames.

7. Technical API Changelog

KPS v4.0.0: Public Theming API & Multi-Client Expansion November 2026

Public Theming API: Published _G.KerzoPostalSuiteAPI with 6 sandboxed methods (RegisterTheme, UnregisterTheme, ApplyTheme, GetCurrentTheme, GetRegisteredThemes, RegisterCallback).
Custom Palette Support: External themes can supply an optional palette table resolved by ObtenerPaletaTema.
Zero-Taint Security: All external callbacks and event listeners execute inside protective pcall blocks.
Full Multi-Client Support: Expanded compatibility across Retail (12.x), WoW Forever (1.60.x), Classic Era (1.15.x), TBC Anniversary (2.5.x), and Classic Progression (5.5.x).