Email Integration

Embed charts in HTML emails for transactional notifications, newsletters, and reports.

How It Works

Email clients load images via <img src="URL">. Chart-Output's GET endpoint returns a chart image when the URL is requested. No JavaScript, no iframes—just a simple image URL.

Because browsers cannot send Authorization headers with image requests, include your API key as a key query parameter instead. The alias apiKey is also accepted.

html

<img 
  src="https://chart-output.com/api/v1/render?key=pk_live_YOUR_API_KEY&type=bar&labels=Jan,Feb,Mar&data=100,150,120&format=png" 
  alt="Monthly Revenue" 
  width="600" 
  height="300" 
/>

The easiest way to get this URL is to build your chart in the Playground and click Email embed — the URL will have your API key included automatically.

Why Images May Not Load (Image Blocking)

Gmail, Outlook, Apple Mail, and Yahoo Mail block external images by default for security. This is normal email behavior, not a bug.

What recipients see

On first open, they see a placeholder with a prompt like "Display images" or "Always display images from [sender]". After clicking once, images from your sender address load automatically in all future emails.

How to improve load rates

Use a recognizable, consistent From address so recipients trust it and click to load images.
Add descriptive alt text so the chart is still meaningful if images are blocked.
Send a plain-text fallback link to the chart image for recipients who have images permanently disabled.

Best Practices

Use PNG format – Best compatibility across Gmail, Outlook, Apple Mail, and Yahoo Mail.
Set explicit dimensions – Include width and height attributes to prevent layout shifts.
Keep URLs under 2000 characters – Use query params for simple charts; use POST + base64 for complex specs.
URL-encode special characters – Spaces, commas in labels, and other reserved chars must be encoded (e.g., %20 for space).
Use descriptive alt text – Improves accessibility when images are blocked.

Transactional Email Example

Order confirmation with a bar chart showing order breakdown.

html

<!DOCTYPE html>
<html>
<body>
  <h1>Order Confirmed</h1>
  <p>Thank you for your order. Here's your order summary:</p>
  <img 
    src="https://chart-output.com/api/v1/render?key=pk_live_YOUR_API_KEY&type=bar&labels=Product%20A,Product%20B,Product%20C&data=2,3,1&title=Items%20Ordered&format=png&width=500&height=250" 
    alt="Order items chart" 
    width="500" 
    height="250"
    style="max-width:100%;height:auto;"
  />
</body>
</html>

Newsletter Example

Monthly stats report with a line chart. Build the URL dynamically in your email template.

html

<!-- In your template (e.g., Handlebars, Liquid, SendGrid) -->
<img 
  src="https://chart-output.com/api/v1/render?key=pk_live_YOUR_API_KEY&type=line&labels={{labels}}&data={{data}}&title=Monthly%20Stats&format=png&width=600&height=300" 
  alt="Monthly performance" 
  width="600" 
  height="300"
/>
<!-- labels and data are template variables with URL-encoded values -->

Troubleshooting

Images not loading

Some email clients block external images by default. Users may need to "Display images" or add your domain to a safe list.
Outlook desktop can be strict with external images. Test in Outlook web and desktop.
Ensure your API URL uses HTTPS. Many clients block HTTP images.

Broken or distorted charts

Check URL encoding. Commas in labels should stay as commas; spaces should be %20.
Verify labels and data have matching lengths.
Test the URL directly in a browser before embedding.

URL too long

For charts with many data points, use the POST endpoint and generate a short redirect URL, or use base64 encoding with the chart parameter.

Testing in Email Clients

Test your emails in Gmail (web + mobile), Outlook (web + desktop), Apple Mail, and Yahoo Mail. Use tools like Litmus or Email on Acid for comprehensive testing, or send test emails to yourself across clients.