AI가 작성한 HTML 이메일이 Outlook에서 깨지는 이유 (그리고 제가 고친 방법)

어떤 AI 코딩 어시스턴트에게 이메일 템플릿을 요청하면, 여러분은 아름다운 것을 받게 될 것입니다. flexbox 레이아웃, border-radius, rgba() 색상, 깔끔한 <button> 등이 포함되어 있죠. 이것을 ESP(Email Service Provider)에 붙여넣고 테스트를 보내 Gmail에서 휴대폰으로 열어보면 완벽합니다.

그런데 고객이 Windows의 Outlook에서 이메일을 열면 마치 몸값 요구 쪽지처럼 보입니다.

이것은 AI가 멍청해서가 아닙니다. AI가 너무 똑똑해서, 현대 웹 개발에 대한 모든 지식을 적용하지만 그 지식 대부분이 해당 환경에서는 사실과 다르기 때문입니다.

이메일 클라이언트는 브라우저가 아니다

모두의 사고방식을 무너뜨리는 사실은 이것입니다: Windows용 Outlook은 Microsoft Word의 엔진으로 HTML 이메일을 렌더링합니다. 브라우저 엔진이 아닙니다. Word입니다. 여러분의 .docx 파일을 렌더링하는 것과 같은 엔진이죠.

이 하나의 사실은 제약 조건들의 더미로 이어집니다:

• flexbox, grid, float 사용 불가. 레이아웃은 마치 2005년처럼 <table> 요소를 사용해 구현해야 합니다.
• max-width 사용 불가. 반응형 컨테이너가 Outlook에서 아무것도 제한하지 못합니다.
• border-radius 사용 불가. 둥근 버튼이 날카로운 직사각형으로 보입니다.
• 특수 VML 마크업 없이는 배경 이미지 사용 불가.
• <div>의 padding은 무시됩니다 — <td>의 패딩만 신뢰할 수 있습니다.
• rgba()와 3자리 헥스 코드는 실패합니다. 6자리 헥스 코드만 가능합니다.

그리고 Outlook만이 함정이 아닙니다:

• Gmail은 단 하나의 CSS 규칙에 구문 오류가 있으면 전체 <style> 블록을 삭제합니다.
• Gmail과 Outlook 모바일은 색상을 반전시키고 미디어 쿼리를 무시하며 다크 모드를 강제 적용합니다.
• Outlook에서는 기본적으로 이미지가 차단됩니다 — 따라서 이메일이 먼저 스타일링된 텍스트로 소통해야 합니다.

이 모든 것은 학습 데이터의

border-radius가 적용된 CSS 버튼은 Outlook에서 사각형으로 나타납니다. 해결책은 하이브리드 방식입니다. 최신 클라이언트용 일반 앵커(anchor) 태그와, 조건부 주석(conditional comments) 내부에 숨겨져 오직 Outlook에서만 보이는 VML <v:roundrect>를 함께 사용하는 것입니다. Outlook에서는 둥근 모서리를 구현하고, 그 외 모든 곳에서는 깔끔한 앵커를 사용하며, 실제 텍스트 기반이기에 이미지가 차단된 상황에서도 정상적으로 작동합니다.

하이브리드 (spongy) 레이아웃

최신 클라이언트에서는 유동적인 너비(fluid width)를 원하지만, Outlook은 고정된 픽셀 너비가 필요합니다. 비결은 <!--[if mso]>로 감싸져 Outlook만 볼 수 있는 "고스트 테이블 (ghost table)"을 사용하는 것입니다. 최신 클라이언트는 max-width를 준수하며 유동적으로 변하지만, Outlook은 고정된 고스트 테이블을 읽어 올바르게 렌더링합니다.

다크 모드 생존 전략

Gmail이나 Outlook 모바일이 색상을 강제로 반전시키는 것을 막을 수는 없지만, 이를 견뎌낼 수 있는 팔레트를 설계하거나, Outlook.com의 독자적인 [data-ogsc] 선택자를 사용하여 다크 모드 재작성(rewrite)에 대응할 수는 있습니다.

이 모든 것을 Claude 스킬로 패키징했습니다

이메일 작업을 할 때마다 Claude에게 이 규칙들을 계속 다시 설명해야 했기에, 이를 Claude 스킬(skill)로 만들었습니다. 이는 에이전트가 이메일 작업을 감지했을 때 자동으로 로드하는 재사용 가능한 지침 팩입니다.

이것은 타협할 수 없는 규칙들이 담긴 SKILL.md와 데이터 파일들로 구성되어 있습니다. 렌더링 엔진별로 그룹화된 25개 이상의 클라이언트에 대한 CSS 지원 매트릭스, 복사해서 바로 쓸 수 있는 불변의 패턴들(버튼, 하이브리드 레이아웃, 다크 모드 키트, 프리헤더(preheader), 컴플라이언스 푸터), 발송 전 QA 체크리스트, 그리고 프로덕션 템플릿이 포함되어 있습니다.

설치는 한 줄이면 끝납니다:

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

설치 후 Claude에게 이메일을 요청하면, 브라우저에서는 맞지만 정작 중요한 곳에서 깨져버리는 코드 대신, 테이블 레이아웃, VML 버튼, 스타일링된 대체 텍스트(alt text), 그리고 다크 모드에 안전한 색상을 사용하는 첫 번째 초안을 작성해 줍니다.

이 프로젝트는 MIT 라이선스이며, 의존성 없이 마크다운(markdown)으로만 구성되어 있습니다. 리포지토리는 아래 링크에서 확인할 수 있으며, README에 Outlook 적용 전후 비교가 포함되어 있습니다:

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

만약 귀하가 전문적으로 이메일 개발 (email development)을 하고 계신다면, 클라이언트 지원 매트릭스 (client-support matrix)를 검토해 주시면 정말 감사하겠습니다. 만약 잘못된 부분을 발견하신다면 이슈 (issue)를 생성해 주세요.