How long does the integration take?

Change one base URL in an OpenAI-compatible client, or install the Python or TypeScript SDK; the quickstart routes a first request in a few minutes.

Will this lock us into another vendor?

No. The router is Apache-2.0 open source, your provider keys stay yours, and the API is OpenAI-compatible, so leaving is a change of base URL.

What happens when a provider fails?

The router falls back to the next model your policy allows and records the fallback in the trace, so an outage costs a retry, not an incident.

padosoft-email-html-builder - Skill

Name: padosoft-email-html-builder
Author: padosoft

Imported from padosoft/skills (skills/padosoft-email-html-builder/SKILL.md). Install upstream with npx skills add padosoft/skills --skill padosoft-email-html-builder. Copyright stays with the author (MIT).

Email HTML Builder

Produces HTML emails that are production ready on the first try: table layout with HTML attributes, inline CSS reduced to typography alone, a minimal <style>, an aligned text/plain part, one-click unsubscribe headers. The expected result on Mailtrap is spam ≤ 0.1 and an HTML Check with only the allowed warnings (§5). On MailUp Check-up: zero problems.

The complete normative rules with R-xxx IDs are in references/rules.md. The linter is scripts/lint_email.py and the reference template is templates/reference-welcome-dark.html. If those files are not available, the essential rules below are enough and are binding.

0. Included scripts

Script	Use
`scripts/lint_email.py`	Rule validator. `python3 scripts/lint_email.py email.html --text email.txt --subject "Subject" [--production] [--transactional] [--json]`. Exit 1 if any MUST is violated, 0 when clean.
`scripts/build_payload.py`	Generates the Mailtrap JSON payload with `List-Unsubscribe` and One-Click. `--help` for the options.
`scripts/send_mailtrap_sandbox.sh` / `.ps1`	Sandbox send. Variables: `MAILTRAP_TOKEN`, `MAILTRAP_INBOX_ID`.
`scripts/screenshot_email.py`	Screenshots at 600px and 375px, with and without `<style>` (requires Playwright; if it is missing, skip gate G2 and say so in the report).
`templates/reference-welcome-dark.html`	Compliant template to start from (0 MUST violated).
`references/rules.md`	Complete `R-xxx` rules. Read it when a warning is not in the §5 baseline, or when you need the rationale behind a rule.

1. Mandatory workflow

Run the phases in order. Do not deliver before G1–G2 are green. If you have access to Mailtrap, run G3–G6 as well.

Brief. Work out or ask (once, in a single batch) what is missing:
- type of email, brand, language and light/dark theme;
- a palette of 2–3 colors, content, CTA and URLs;
- sending platform (MailUp, Mailtrap Sending, SES…) and the syntax of the dynamic fields;
- legal details for the footer.
If the brief is incomplete do not stall: use explicit placeholders and list them in the report.
Content design. Before writing code, settle:
- subject: 35–50 characters;
- preheader: 40–100 characters, complementary to the subject;
- a single primary CTA;
- text/image ratio ≥ 80/20;
- which blocks to use (header, hero, card, benefits, social, footer).
Code. Start from the skeleton in §3 (or from templates/). Apply every MUST rule in §4.
Text/plain. Write the text-only version with the same content and the same links in clear text.
G1 Lint. Run python3 scripts/lint_email.py email.html --text email.txt --subject "…" and bring the violated MUSTs to 0. If the script is not there, work through the §6 checklist by hand.
G2 Render. Take screenshots with Playwright/Chromium at 600px and 375px, then repeat them without <style> and with images blocked. No breakage allowed.
Payload and test send.
- scripts/build_payload.py generates the JSON payload (List-Unsubscribe included);
- the send starts with scripts/send_mailtrap_sandbox.{ps1,sh} or with the Mailtrap connector (send-sandbox-email);
- on Windows use PowerShell: $env:VAR="…" and not the VAR=… cmd syntax.
Without Mailtrap (no account or connector): declare G3–G6 as not run in the report, do not estimate them, and in exchange work through the manual checklist in §6 on top of the linter. Deliver anyway.
G3–G6 Mailtrap verification. Use get-sandbox-message-html-analysis, get-sandbox-message-spam-score and the blacklist and text reports. Compare against the §5 baseline: every entry outside the baseline is a defect to fix and resend. Do not declare a removable warning a "false positive".
G7 MailUp (if that is the sending platform): Check-up with no errors on blacklisted links, tracking enabled, unsubscribe present, weight, dynamic fields with defaults, summary, analytics, custom tracking domain, spam and code.
Delivery.
- .html, .txt and payload.json files;
- a report with the outcome of the gates, remaining warnings with their rationale, placeholders still to be replaced and SHOULD exceptions with their rationale;
- a version number (v1, v2…) in the test subject.

2. Key principle (the cause of the historical mistakes)

The Mailtrap checker uses caniemail.com data and reports every CSS property present, even when there is a fallback. bgcolor next to background-color does not remove the warning: the CSS property has to be deleted. → Layout with HTML attributes. Inline CSS for typography only. <style> only for rounded corners and media queries.

3. Reference skeleton

<!DOCTYPE html>
<html lang="en" xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="x-apple-disable-message-reformatting">
<meta name="format-detection" content="telephone=no, date=no, address=no, email=no, url=no">
<meta name="color-scheme" content="dark">
<meta name="supported-color-schemes" content="dark">
<title>Title</title>
<!--[if mso]><noscript><xml><o:OfficeDocumentSettings><o:AllowPNG/><o:PixelsPerInch>96</o:PixelsPerInch></o:OfficeDocumentSettings></xml></noscript><![endif]-->
<style>
.r10{border-radius:10px}.r9{border-radius:9px}.r9t{border-radius:9px 9px 0 0}
@media (max-width:620px){.wrap{width:100%!important}.col{display:block!important;width:100%!important}.vgap{display:block!important;width:100%!important;height:16px!important}.gut{width:20px!important}.h1m{font-size:26px!important;line-height:32px!important}.txtm{font-size:16px!important;line-height:24px!important}.imgm{width:100%!important;height:auto!important}}
</style>
</head>
<body bgcolor="#04050a" text="#aab3c5" link="#2ff5d6" vlink="#2ff5d6" alink="#2ff5d6" marginwidth="0" marginheight="0" topmargin="0" leftmargin="0">
<!--[if !mso]><!--><div aria-hidden="true" style="display:none; mso-hide:all;">Preheader of 40-100 characters, no invisible filler.</div><!--<![endif]-->
<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" bgcolor="#04050a">
 <tr><td height="32" style="font-size:1px; line-height:32px;">&nbsp;</td></tr>
 <tr><td align="center" valign="top">
  <table role="presentation" width="632" class="wrap" align="center" cellpadding="0" cellspacing="0" border="0"><tr>
   <td width="16" style="font-size:1px; line-height:1px;">&nbsp;</td>
   <td align="center" valign="top">
    <table role="presentation" class="wrap" width="600" align="center" cellpadding="0" cellspacing="0" border="0">
     <!-- blocks -->
    </table>
   </td>
   <td width="16" style="font-size:1px; line-height:1px;">&nbsp;</td>
  </tr></table>
 </td></tr>
 <tr><td height="32" style="font-size:1px; line-height:32px;">&nbsp;</td></tr>
</table>
</body>
</html>

Block patterns (copy them, do not reinvent them)

Vertical and horizontal spacing (instead of padding):

<tr><td height="24" style="font-size:1px; line-height:24px;">&nbsp;</td></tr>
<td class="gut" width="24" style="font-size:1px; line-height:1px;">&nbsp;</td>

Card with border and corners (instead of border and background-color):

<table role="presentation" class="r10" width="100%" cellpadding="1" cellspacing="0" border="0" bgcolor="#1c2333"><tr><td>
  <table role="presentation" class="r9" width="100%" cellpadding="0" cellspacing="0" border="0" bgcolor="#0d1018">
    <tr><td colspan="3" height="24" style="font-size:1px; line-height:24px;">&nbsp;</td></tr>
    <tr><td width="20" style="font-size:1px; line-height:1px;">&nbsp;</td><td><!-- content --></td><td width="20" style="font-size:1px; line-height:1px;">&nbsp;</td></tr>
    <tr><td colspan="3" height="24" style="font-size:1px; line-height:24px;">&nbsp;</td></tr>
  </table>
</td></tr></table>

Accessible H1 heading (no <h1>):

<td align="center" class="h1m" role="heading" aria-level="1" style="font-family:Arial, Helvetica, sans-serif; font-size:30px; line-height:38px; font-weight:700; color:#f2f4f8;">Title</td>

Bulletproof CTA (VML and HTML with identical dimensions):

<!--[if mso]>
<v:roundrect xmlns:v="urn:schemas-microsoft-com:vml" xmlns:w="urn:schemas-microsoft-com:office:word" href="https://…" style="height:48px; v-text-anchor:middle; width:220px;" arcsize="21%" fillcolor="#2ff5d6" stroke="f"><w:anchorlock/><center style="color:#04050a; font-family:Arial, Helvetica, sans-serif; font-size:15px; font-weight:bold;">Browse the products</center></v:roundrect>
<![endif]-->
<!--[if !mso]><!-->
<table role="presentation" class="r10" width="220" cellpadding="0" cellspacing="0" border="0" bgcolor="#2ff5d6"><tr>
<td align="center" height="48" style="font-family:Arial, Helvetica, sans-serif; font-size:15px; line-height:48px; font-weight:700;"><a href="https://…" target="_blank" style="color:#04050a; text-decoration:none;">Browse the products</a></td>
</tr></table>
<!--<![endif]-->

Image in a card (the cell carries height and bgcolor, so it stays intact when images are blocked):

<td align="center" valign="middle" height="120" class="r9t" bgcolor="#161b27" style="font-size:0; line-height:0;"><a href="https://…" target="_blank"><img src="https://cdn.example.com/img/x@2x.jpg" width="174" height="120" border="0" alt="Short description" class="imgm"></a></td>

Columns that stack on mobile (whole px, sum = container):

<tr><td class="col" width="176" valign="top">…</td><td class="vgap" width="12" style="font-size:1px; line-height:1px;">&nbsp;</td><td class="col" width="176" valign="top">…</td><td class="vgap" width="12" style="font-size:1px; line-height:1px;">&nbsp;</td><td class="col" width="176" valign="top">…</td></tr>

Divider:

<tr><td height="1" bgcolor="#1c2333" style="font-size:1px; line-height:1px;">&nbsp;</td></tr>

4. Essential MUST rules (IDs in `references/rules.md`)

Structure and weight

Tables only, role="presentation" cellpadding="0" cellspacing="0" border="0", a 600px container, a 16px outer gutter built with cells (R-004/005/006).
Forbidden: <h1>, <script>, <form>, <iframe>, <video>, <svg>, <link>, @import, the on* handlers, empty tags and superfluous comments (R-007/008/009/011).
HTML under 100 KB (target 40 KB). Images ≤ 50 KB, GIFs ≤ 100 KB with a complete first frame (R-050/052/604).

CSS

Inline, only font-family, font-size, line-height, font-weight, font-style, letter-spacing, color, text-decoration, text-align and mso-* are allowed (R-100).
Forbidden inline: padding, margin, background, border, border-radius, width, height, max/min-*, display, opacity, overflow, visibility, outline, box-shadow, position, float, text-transform, table-layout (R-101). The only exception is the preheader (display:none; mso-hide:all).

Mandatory substitutions (R-200…210):

Instead of	Use
`background`	`bgcolor`
padding	empty cells with `height`/`width`
border	outer table with `bgcolor` + `cellpadding="1"`
CSS width/height	`width`/`height` attributes
body margins	`marginwidth`/`marginheight`
default color	`text`/`link` on `<body>`
gap under images	`font-size:0; line-height:0` on the cell
background images	a solid color

A single <style>, with one line of border-radius and one line of @media (max-width:620px){…}, without only screen and. No reset, no preheader classes, no prefers-color-scheme or :root (R-300…303).
No comment containing the string <style. The email must stay readable even without the style block (R-304/305).

Antispam and deliverability

Marketing vs transactional. The unsubscribe rules (R-405 List-Unsubscribe header, R-454 footer link) apply to commercial and bulk email. For a purely transactional one (order confirmation, password reset, shipping) they are not required: use --transactional in the linter, still keep an "Email preferences" link, and state it in the report. All the other rules apply to both.
HTML 100% ASCII: accented characters as numeric entities (è) (R-402).
Never use invisible filler in the preheader (͏, &zwnj;, repeated  ): it costs +2.4 SpamAssassin points (R-401).
Preheader without color. No text in a color equal or close to the background, separators included (R-400/403).
Text/plain aligned with the HTML. List-Unsubscribe and List-Unsubscribe-Post: List-Unsubscribe=One-Click headers (R-404/405).
Subject 35–50 characters (60 max): no ALL CAPS, no !!!, no trigger words or more than one emoji (R-406).
Spam target ≤ 0.1, blacklist 0, no shorteners or bare IPs. Text/images ≥ 80/20. Sender domain with SPF+DKIM+DMARC, a monitored Reply-To (R-407…412).

Links (MailUp Check-up)

Absolute, working HTTPS links. Tracking enabled with a custom tracking domain (R-450/451).
UTM utm_source, utm_medium=email, utm_campaign, without spaces (R-452).
Dynamic fields in the platform syntax (MailUp [field]) with a default value. In links the protocol must be explicit (https://[field]) (R-453).
Unsubscribe in the footer, two clicks at most (R-454). tel: without spaces, asset paths without spaces (R-457/458).

Design and accessibility

color-scheme = dark or light, never light dark without a complete dark theme (R-500).
Calculated contrast ≥ 4.5:1 for every normal text, footer included (R-501).
Fonts: headings ≥ 22px, body ≥ 16px on mobile (.txtm class), legal ≥ 12px, CTA ≥ 15px. A palette of 2–3 colors (R-502/503).
aria-hidden on glyphs and separators. lang and <title> filled in. DOM order = visual order (R-504/505).
<img> with width, height, border="0", a short alt, HTTPS src from the brand CDN (no placeholders). The cell carries height and bgcolor. Never put essential text inside an image only (R-600…603).
CTA VML + HTML with identical dimensions, area ≥ 46×46px, a single primary CTA (R-700…703).
Columns in whole px (no 33.33%), no spacing asymmetry when they stack (R-800…802).

Footer: reason for receiving, legal entity, address, VAT number, contacts, Unsubscribe, Preferences, Privacy, copyright and social. In production, zero placeholders (R-900/901).

5. Mailtrap baseline (the only allowed warnings)

Rule	Reason
`style`	The style block is needed for responsive and corners
`@media`, `@media max-width`	Mobile media queries
`width`/`display`/`height`/`font-size`/`line-height` inside the media query	Stacked columns and mobile typography
`border-radius` (1 line)	On Outlook the corners stay square
`display` on the preheader	It is the only way to hide it

SpamAssassin in testing: MISSING_MID 0.1 (the production MTA adds the Message-ID) and HTML_MESSAGE 0.0. Any other entry has to be fixed.

Mailtrap Market Support ≥ 95% (for Mailtrap ≥ 90% is acceptable, below 85% it has to be redone).

6. Manual checklist (when the linter is not there)

7. Delivery report format

Version: vN  |  HTML weight: xx KB  |  Subject: "…" (nn chars)  |  Preheader: nn chars
G1 Lint: PASS (0 MUST, n SHOULD)      G2 Render: PASS (600/375/no-style/img-off)
G3 HTML Check: xx% — warnings: [baseline only | list of extras + fix]
G4 Spam: 0.1 (MISSING_MID)            G5 Blacklist: 0      G6 HTML/Text: aligned
G7 MailUp Check-up: [outcome | not run]
SHOULD exceptions with rationale: …
Placeholders to replace: …
Next step: …

Always flag the uncertainties explicitly, for example the syntax of the platform's unsubscribe placeholder that still has to be verified on the account.

padosoft-email-html-builder

About

Email HTML Builder

0. Included scripts

1. Mandatory workflow

2. Key principle (the cause of the historical mistakes)

3. Reference skeleton

Block patterns (copy them, do not reinvent them)

4. Essential MUST rules (IDs in `references/rules.md`)

5. Mailtrap baseline (the only allowed warnings)

6. Manual checklist (when the linter is not there)

7. Delivery report format

Install padosoft-email-html-builder and it becomes one more candidate the router can pick - when it fits.

What it costs to adopt - in engineering time.

One base URL

No vendor lock-in

Failover built in

Use it

Manifest

Reviews

About

Email HTML Builder

0. Included scripts

1. Mandatory workflow

2. Key principle (the cause of the historical mistakes)

3. Reference skeleton

Block patterns (copy them, do not reinvent them)

4. Essential MUST rules (IDs in references/rules.md)

5. Mailtrap baseline (the only allowed warnings)

6. Manual checklist (when the linter is not there)

7. Delivery report format

Install padosoft-email-html-builder and it becomes one more candidate the router can pick - when it fits.

What it costs to adopt - in engineering time.

One base URL

No vendor lock-in

Failover built in

Use it

Manifest

Reviews

4. Essential MUST rules (IDs in `references/rules.md`)