Send Email in HTML

Send transactional emails using raw HTML content

MethodPOST

/api/v1/emails

The HTML content type allows you to send raw HTML emails with full design control. Use this when you have existing HTML templates or need pixel-perfect layouts.

Building templates as React components? See Send React Email Templates with Lumail.

Quick Example

curl -X POST https://lumail.io/api/v1/emails \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "subject": "Welcome {{name}}!",
    "content": "<html><body><h1>Hello {{name}}!</h1><p>Welcome to our platform.</p></body></html>",
    "contentType": "HTML",
    "from": "[email protected]"
  }'

import { Lumail } from "lumail";
const lumail = new Lumail({ apiKey: "YOUR_API_TOKEN" });

await lumail.emails.send({
  to: "[email protected]",
  subject: "Welcome {{name}}!",
  content:
    "<html><body><h1>Hello {{name}}!</h1><p>Welcome to our platform.</p></body></html>",
  contentType: "HTML",
  from: "[email protected]",
});

Variable Substitution

Use double curly braces in your HTML to insert subscriber data:

<h1>Hello {{name | 'Friend'}}!</h1>
<p>Your email is {{email}}.</p>

Available Variables

Variable	Description
`{{name}}`	Subscriber's name
`{{email}}`	Subscriber's email address
`{{phone}}`	Subscriber's phone number
`{{unsubscribeUrl}}`	Unsubscribe link (empty on transactional sends)
`{{onlineUrl}}`	View in browser link
`{{customField}}`	Any custom field

Placeholder names must be word characters. Hyphenated organization variables such as {{org-name}} are not substituted in HTML content and are delivered literally.

Complete Example

{
  "to": "[email protected]",
  "subject": "Your order #{{orderNumber}} is confirmed!",
  "contentType": "HTML",
  "content": "<!DOCTYPE html><html><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\"></head><body style=\"font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto; padding: 20px;\"><h1 style=\"color: #333;\">Thanks for your order, {{name}}!</h1><p>Your order <strong>#{{orderNumber}}</strong> has been confirmed.</p><table style=\"width: 100%; border-collapse: collapse; margin: 20px 0;\"><tr><td style=\"padding: 10px; border-bottom: 1px solid #eee;\">Total:</td><td style=\"padding: 10px; border-bottom: 1px solid #eee;\">{{orderTotal}}</td></tr><tr><td style=\"padding: 10px; border-bottom: 1px solid #eee;\">Shipping:</td><td style=\"padding: 10px; border-bottom: 1px solid #eee;\">{{shippingMethod}}</td></tr></table><p>Questions? <a href=\"mailto:[email protected]\">Contact us</a></p></body></html>",
  "from": "[email protected]",
  "preview": "Your order has been confirmed"
}

Email-Safe HTML Guidelines

Use Inline Styles

Email clients have limited CSS support. Always use inline styles:

<!-- Good -->
<p style="color: #333; font-size: 16px;">Hello!</p>

<!-- Avoid -->
<style>
  .text {
    color: #333;
  }
</style>
<p class="text">Hello!</p>

Use Tables for Layout

For complex layouts, use tables instead of flexbox or grid:

<table width="100%" cellpadding="0" cellspacing="0">
  <tr>
    <td width="50%" style="padding: 10px;">Left column</td>
    <td width="50%" style="padding: 10px;">Right column</td>
  </tr>
</table>

Set Image Dimensions

Always specify width and height for images:

<img
  src="https://example.com/logo.png"
  width="200"
  height="50"
  alt="Company Logo"
  style="display: block;"
/>

Use Web-Safe Fonts

Stick to fonts available on all systems:

<p style="font-family: Arial, Helvetica, sans-serif;">Safe fonts</p>
<p style="font-family: Georgia, Times, serif;">Safe serif</p>

Automatic Features

When using HTML format, Lumail automatically:

Adds unsubscribe link on non-transactional sends when {{unsubscribeUrl}} is absent (appended at the bottom)
Adds tracking pixel for open tracking, inserted before </body>
Generates plain text version by stripping HTML tags

Click tracking rewrites Markdown-style [text](url) links, so <a href> URLs in HTML content are delivered unchanged.

Including Unsubscribe Link

If you want to control the placement of the unsubscribe link, include it in your HTML:

<p style="text-align: center; font-size: 12px; color: #666;">
  <a href="{{unsubscribeUrl}}">Unsubscribe</a>
</p>

If you don't include {{unsubscribeUrl}}, Lumail will automatically append an unsubscribe link at the bottom of your email.

Best Practices

Test across email clients - Use tools like Litmus or Email on Acid
Keep width under 600px - Ensures proper display on mobile
Use alt text for images - Many clients block images by default
Avoid JavaScript - Not supported in email clients
Include plain text fallback - Lumail generates this automatically
Use absolute URLs - Relative URLs won't work in emails

PreviousExecute Tool NextSend Email in Markdown