Skip to main content

Building Responsive Email Templates

Transactional emails must render correctly across dozens of clients — from Gmail to Outlook to low-end mobile. This guide covers responsive structure, variables, and the HTML rules that keep templates from breaking.

🚀 Quick Start​

curl -X POST https://api.afriroute.ai/api/v1/email/templates \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "receipt",
    "subject": "Your receipt for order {{order_id}}",
    "html": "<h1>Thanks {{name}}!</h1><p>You paid {{amount}}.</p>"
  }'

🔤 Variables​

Templates use {{name}} placeholders filled at send time.

await fetch('https://api.afriroute.ai/api/v1/email/send', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer $AFRIROUTE_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    to: '[email protected]',
    template: 'receipt',
    variables: { name: 'Amina', order_id: 'A1029', amount: 'KES 2,400' }
  })
});
import requests
requests.post(
    'https://api.afriroute.ai/api/v1/email/send',
    headers={'Authorization': 'Bearer $AFRIROUTE_API_KEY'},
    json={
        'to': '[email protected]',
        'template': 'receipt',
        'variables': {'name': 'Bola', 'order_id': 'A1030', 'amount': 'NGN 5,000'}
    }
)

Always provide defaults so a missing variable renders blank, not {{name}}.

🧱 Responsive HTML Rules​

Email HTML is not web HTML. Outlook still uses a Word rendering engine.

RuleWhy
Use tables for layoutFlexbox/grid unsupported in many clients
Inline CSS<style> blocks stripped by some clients
Max width ~600pxFits mobile and desktop
Set explicit image widthsPrevents broken layouts
Provide alt textImages blocked by default
<table role="presentation" width="100%" style="max-width:600px;margin:0 auto;">
  <tr><td style="padding:24px;font-family:Arial,sans-serif;">
    <h1 style="font-size:20px;">Thanks {{name}}!</h1>
    <p style="font-size:14px;color:#333;">Order {{order_id}} — {{amount}}</p>
  </td></tr>
</table>

📄 Plain-Text Alternative​

Always include a plain-text version. It improves deliverability and serves text-only clients.

{
  "html": "<p>Your OTP is {{code}}</p>",
  "text": "Your OTP is {{code}}"
}

💡 Best Practices​

  • Inline all CSS — use a build step or inliner.
  • Test in real clients (Gmail, Outlook, iOS Mail) before launch.
  • Keep under 102KB — Gmail clips longer emails.
  • Always include plain text alongside HTML.
  • Use a single clear CTA and make it a tappable button.
  • Provide variable defaults to avoid empty placeholders.

📚 Related Resources​

Last Updated: May 2026