DEV Community: Jayesh Bansal

Why your AI writes HTML email that breaks in Outlook (and how I fixed it)

Jayesh Bansal — Thu, 11 Jun 2026 10:38:16 +0000

Ask any AI coding assistant for an email template and you'll get something beautiful: flexbox layout, border-radius, rgba() colors, a clean <button>. Paste it into your ESP, send a test, open it in Gmail on your phone — perfect.

Then a customer opens it in Outlook on Windows and it looks like a ransom note.

This isn't the AI being dumb. It's the AI being too smart — applying everything it knows about modern web development to a medium where most of that knowledge is actively wrong.

Email clients are not browsers

Here's the fact that breaks everyone's mental model: Outlook for Windows renders HTML email with Microsoft Word's engine. Not a browser engine. Word. The same thing that renders your .docx files.

That one fact cascades into a pile of constraints:

No flexbox, no grid, no floats. Layout has to be done with <table> elements, like it's 2005.
No max-width. Your responsive container doesn't constrain anything in Outlook.
No border-radius. Your rounded button is a sharp rectangle.
No background images without special VML markup.
padding on a <div> is ignored — only <td> padding is reliable.
rgba() and 3-digit hex fail. Six-digit hex only.

And Outlook isn't even the only landmine:

Gmail clips your email at 102KB of HTML. Everything past the cut — including your unsubscribe link and tracking pixel — just vanishes behind a "[Message clipped]" link.
Gmail drops your entire <style> block if a single CSS rule has a syntax error.
Gmail and Outlook mobile force dark mode by inverting your colors, ignoring your media queries.
Images are blocked by default in Outlook — so your email has to communicate as styled text first.

None of this is in the training data's "best practices for HTML/CSS," because none of it is true for browsers. So the AI confidently generates browser-correct code that fails in the one place corporate email actually gets read.

The patterns that actually work

Email developers have spent fifteen years figuring out the workarounds.

Bulletproof buttons

A CSS button with border-radius is square in Outlook. The fix is a hybrid: a normal anchor for modern clients, plus a VML <v:roundrect> that only Outlook sees, hidden from everyone else inside conditional comments. Rounded corners in Outlook, clean anchor everywhere else, and it works with images blocked because it's real text.

The hybrid (spongy) layout

You want fluid width on modern clients but Outlook needs a fixed pixel width. The trick is a "ghost table" wrapped in <!--[if mso]> that only Outlook sees. Modern clients honor max-width and go fluid; Outlook reads the fixed ghost table and renders correctly.

Dark mode survival

You can't stop Gmail/Outlook mobile from force-inverting colors, but you can design palettes that survive it, and target Outlook.com's dark-mode rewrite with its proprietary [data-ogsc] selectors.

I packaged all of it into a Claude skill

I kept re-explaining these rules to Claude on every email task, so I turned them into a Claude skill — a reusable instruction pack the agent loads automatically when it detects an email task.

It's just a SKILL.md with the non-negotiable rules plus data files: a CSS support matrix for 25+ clients grouped by rendering engine, copy-paste bulletproof patterns (the button, hybrid layout, dark-mode kit, preheader, compliance footer), a pre-send QA checklist, and production templates.

Install is one line:

git clone https://github.com/jayesh-bansal/email-pro-max.git ~/.claude/skills/email-pro-max

After that, when you ask Claude for an email, the first draft uses table layout, VML buttons, styled alt text, and dark-mode-safe colors — instead of browser-correct code that breaks where it matters.

It's MIT, zero dependencies, just markdown. Repo here, with a before/after Outlook comparison in the README:

→ https://github.com/jayesh-bansal/email-pro-max

If you do email development professionally, I'd genuinely love a second pair of eyes on the client-support matrix — open an issue if you catch something it gets wrong.

Generate Zod schemas from any JSON API — no OpenAPI spec required

Jayesh Bansal — Thu, 11 Jun 2026 10:20:45 +0000

I built this after the nth time I hand-typed a third-party API response into a Zod schema, squinting at the JSON trying to figure out which fields were nullable.

Tools like orval and openapi-typescript are great — if the API has an OpenAPI spec. But most third-party APIs, internal services, and quick prototypes don't. So I built apitype: point it at any URL or JSON and it infers the full schema from the actual data.

npx @jayeshbansal/apitype https://api.github.com/users/octocat --name GithubUser

import { z } from 'zod'

export const githubUserSchema = z.object({
  login: z.string(),
  id: z.number().int().nonnegative(),
  avatar_url: z.string().url(),
  created_at: z.string().datetime(),
  public_repos: z.number().int().nonnegative(),
  // ...
})

export type GithubUser = z.infer<typeof githubUserSchema>

What makes it more than `JSON.parse` + guesswork

Format detection. It recognizes 14 string formats from the values — UUID, email, URL, ISO datetime, IP, JWT, CUID, NanoID, base64, semver, hex color — and emits the matching Zod validator (.uuid(), .email(), .datetime()) instead of a bare z.string().

Nullable/optional inference by sampling. A single response can't tell you whether bio is always null or sometimes a string. So apitype can fetch an endpoint N times and merge the samples: a key that's missing in some responses becomes .optional(), a key that's null in some becomes .nullable().

npx @jayeshbansal/apitype https://api.example.com/posts/random --samples 5 --name Post

Four output formats. Same engine, your choice of target:

zod — Zod schema + inferred type
typebox — TypeBox with Static<>
typescript — plain export type, zero runtime
jsonschema — JSON Schema draft-07

The part I actually care about: it's an MCP server

The same inference engine runs as a Model Context Protocol server, so AI coding assistants (Claude, Cursor, Windsurf) can call apitype as a tool:

{ "mcpServers": { "apitype": { "command": "npx", "args": ["@jayeshbansal/apitype", "--mcp"] } } }

Now when you ask your assistant to "type this API response," it doesn't hallucinate a schema — it calls a deterministic tool that fetched the real data and detected the real formats.

There's also a Vite plugin (regenerate types on dev-server start), a batch config mode (keep a whole API's types in sync in CI), and a programmatic API (import { fromUrl } from '@jayeshbansal/apitype').

When you should not use this

Honesty matters: if your API ships an OpenAPI/Swagger spec, use a spec-based generator. The spec is the source of truth — inference is only as good as the sample responses you feed it. apitype is for the (very common) case where no spec exists.

Try it

npx @jayeshbansal/apitype <url|file>           # one-off, no install
npm install -D @jayeshbansal/apitype           # project dependency

Repo: https://github.com/jayesh-bansal/apitype · MIT, zero runtime deps.

If you hit an API whose shape it gets wrong, open an issue with the response — those are the best test cases.