`-based layouts for modern email clients with Outlook-specific `` fallbacks wrapped in MSO conditional comments. This produces cleaner HTML, better accessibility, and smaller file sizes compared to pure table-based output. **Hybrid mode is off by default.** The default output uses pure table-based markup for maximum compatibility. ## Quick Start ```bash # CLI flag inky build src/ -o dist/ --hybrid # Or in inky.config.json {"src": "src/emails", "dist": "dist", "hybrid": true} ``` ## How It Works In table mode (default), a container outputs: ```html

...

``` In hybrid mode, the same container outputs: ```html

...

``` Modern email clients (Apple Mail, Gmail, Yahoo, etc.) use the `

` with CSS. Microsoft Outlook (which uses the Word rendering engine) sees the `` inside the `

Left

Right

``` ## CLI Usage ```bash # Build with hybrid output inky build email.inky --hybrid # Watch with hybrid output inky watch src/ -o dist/ --hybrid # Serve with hybrid output inky serve src/ --hybrid ``` ## Configuration Add `hybrid` to `inky.config.json`: ```json { "src": "src/emails", "dist": "dist", "hybrid": true } ``` The `--hybrid` CLI flag overrides the config file. ## Language Bindings ### Node.js (WASM) ```js const inky = require("inky"); const html = inky.transformHybrid('Hello'); ``` ### FFI (PHP, Python, Ruby) ```python import inky html = inky.transform_hybrid('Hello') ``` ## When to Use Hybrid Mode **Use hybrid mode when:** - You want cleaner, more semantic HTML - Accessibility is a priority (screen readers handle `

` better than nested tables) - You need smaller file sizes (important for Gmail's 102KB clipping limit) - Your audience primarily uses modern email clients **Stick with table mode when:** - You need maximum compatibility with older/niche email clients - You're targeting environments where Outlook is the primary client (tables render more predictably in Outlook) - You're migrating from v1 and want identical output behavior --- # Language Bindings Inky provides official bindings for Node.js, PHP, Python, and Ruby. All bindings expose the same core API surface. For complete working examples with build scripts and email sending, see: [Node.js](https://github.com/foundation/inky-example-node) | [PHP](https://github.com/foundation/inky-example-php) | [Python](https://github.com/foundation/inky-example-python) | [Ruby](https://github.com/foundation/inky-example-ruby) | [Go](https://github.com/foundation/inky-example-go) ## Common API Every binding provides these functions: | Function | Description | |----------|-------------| | `transform(html, columns?)` | Transform Inky HTML into email-safe table markup | | `transformInline(html)` | Transform and inline CSS from ` `); // Transform with data merge const merged = inky.transformWithData( '', JSON.stringify({ url: "https://example.com", text: "Click" }) ); // Migrate v1 to v2 const migrated = inky.migrate('Content'); // Migrate with change details const result = inky.migrateWithDetails('Content'); // result.html => 'Content' // result.changes => [' -> ', ...] // Validate const diagnostics = inky.validate(''); // [{ severity: "error", rule: "button-no-href", message: "..." }] const diagnostics16 = inky.validate(html, { columns: 16 }); // Version console.log(inky.version()); // "2.0.0" ``` ### TypeScript Type definitions are included. Key types: ```ts interface TransformOptions { columns?: number; } interface ValidateOptions { columns?: number; } interface Diagnostic { severity: "warning" | "error"; rule: string; message: string; } interface MigrateResult { html: string; changes: string[]; } ``` --- ## PHP **Package:** `foundation/inky` on Packagist **Engine:** Native shared library via FFI (or PECL extension) **Requires:** PHP >= 8.1 ### Install ```bash composer require foundation/inky ``` You also need the `libinky` shared library available. Build it from source: ```bash cargo build -p inky-ffi --release # produces target/release/libinky.dylib (macOS) or libinky.so (Linux) ``` ### Driver Setup The PHP package auto-detects the best available driver: | Priority | Driver | Mechanism | Best For | |----------|--------|-----------|----------| | 1 | PECL Extension | `ext-inky` | Shared hosting, production | | 2 | FFI | `ext-ffi` + `libinky` | Local dev, self-managed servers | **FFI setup** -- enable in `php.ini`: ```ini # Option A: Enable globally (dev) ffi.enable = true # Option B: Preload mode (production, more secure) ffi.enable = preload opcache.preload = /path/to/vendor/inky/preload.php ``` Note: `ffi.enable` is a `PHP_INI_SYSTEM` directive and cannot be changed with `ini_set()`. ### API ```php use Inky\Inky; // Transform $html = Inky::transform(''); $html = Inky::transform('Content', columns: 16); // Transform + inline CSS $html = Inky::transformInline(''); // Transform with data merge $html = Inky::transformWithData( '', json_encode(['url' => 'https://example.com', 'text' => 'Click']) ); // Migrate $html = Inky::migrate('Content'); // Migrate with details $result = Inky::migrateWithDetails('Content'); // $result['html'] => 'Content' // $result['changes'] => [' -> ', ...] // Validate $diagnostics = Inky::validate(''); // [['severity' => 'error', 'rule' => 'button-no-href', 'message' => '...']] // Version echo Inky::version(); // "2.0.0" ``` --- ## Python **Package:** `inky-email` on PyPI **Engine:** Native shared library via ctypes **Requires:** Python >= 3.8 ### Install ```bash pip install inky-email ``` You also need the `libinky` shared library. Build from source: ```bash cargo build -p inky-ffi --release ``` The library searches these paths automatically: 1. `target/release/` (development) 2. Bundled with the package 3. `/usr/local/lib/` 4. `/usr/lib/` ### API ```python import inky # Transform html = inky.transform('') html = inky.transform('Content', columns=16) # Transform + inline CSS html = inky.transform_inline('') # Transform with data merge html = inky.transform_with_data( '', '{"url": "https://example.com", "text": "Click"}' ) # Migrate html = inky.migrate('Content') # Migrate with details result = inky.migrate_with_details('Content') # result['html'] => 'Content' # result['changes'] => [' -> ', ...] # Validate diagnostics = inky.validate('') # [{'severity': 'error', 'rule': 'button-no-href', 'message': '...'}] # Version print(inky.version()) # "2.0.0" ``` Note: Python uses `snake_case` -- `transform_inline`, `migrate_with_details`. --- ## Ruby **Package:** `inky-email` on RubyGems **Engine:** Native shared library via Fiddle **Requires:** Ruby >= 2.7 ### Install ```bash gem install inky-email ``` Or in your `Gemfile`: ```ruby gem "inky-email" ``` You also need the `libinky` shared library. Build from source: ```bash cargo build -p inky-ffi --release ``` The library searches these paths automatically: 1. `target/release/` (development) 2. Bundled with the gem 3. `/usr/local/lib/` 4. `/usr/lib/` ### API ```ruby require "inky" # Transform html = Inky.transform('') html = Inky.transform('Content', columns: 16) # Transform + inline CSS html = Inky.transform_inline('') # Transform with data merge html = Inky.transform_with_data( '', '{"url": "https://example.com", "text": "Click"}' ) # Migrate html = Inky.migrate('Content') # Migrate with details result = Inky.migrate_with_details('Content') # result[:html] => 'Content' # result[:changes] => [' -> ', ...] # Validate diagnostics = Inky.validate('') # [{severity: "error", rule: "button-no-href", message: "..."}] # Version puts Inky.version # "2.0.0" ``` --- ## Building the Shared Library PHP, Python, and Ruby bindings all depend on the `libinky` shared library from `inky-ffi`. To build it: ```bash cd /path/to/inky cargo build -p inky-ffi --release ``` This produces: - **macOS:** `target/release/libinky.dylib` - **Linux:** `target/release/libinky.so` - **Windows:** `target/release/inky.dll` For production, copy the library to a system path (`/usr/local/lib/`) or bundle it with your package. ## Building the WASM Module The Node.js binding uses the WASM module from `inky-wasm`: ```bash cd crates/inky-wasm wasm-pack build --target nodejs ``` This generates the `.wasm` file and JS/TS wrapper in `pkg/`. --- # Email Development Guide A practical guide to building HTML emails that render correctly across every major client. These tips apply whether you're using Inky's CLI, language bindings, or writing raw HTML. --- ## How Email HTML Differs from Web HTML Email clients are not browsers. Most strip `

Welcome!

Order Confirmed Thank you for your purchase

Hello {{ user.name }}!

{{ headline }}