Integration guide for email

Learn how to manage email content end-to-end through the Design Studio API.

Our Design Studio API lets you create, manage, and test content including translations and custom components. These endpoints make it possible for you to fully manage the lifecycle of an email programmatically and import emails designed outside of Customer.io.

If your messages contain assets like images, upload them first through the Assets endpoint and then use the returned URLs in your content.

The Design Studio and Assets APIs run on the same host and use the same App API Key for authentication. The same is true for sending these messages through a workflow, so one key covers your whole integration.

How it works

1. Design your email in your external tool.
   • Make sure your asset files are publicly hosted or uploaded to your assets library.
   • Follow the content best practices below.
2. In Workspace settings, create an App API key for authentication.
3. Push the HTML to Customer.io through the Emails endpoints.
4. Check the email before you send it: review it for issues, preview it with sample data, and send a test to your own inbox.
5. (Optional) Request inbox previews to compare how it’d render across email clients.
6. Link the email to an automation, broadcast, or transactional message, then publish any future changes to push them to that workflow.
7. Send the email from your workflow. To send a transactional message, one-time send, or API-triggered broadcast, call the App API. You can’t start an automation through the API.

What you can’t do through the API

The Design Studio API covers the full path from importing content to publishing it. The API only manages content made with Design Studio.

You can’t do the following things with the API:

• Manage emails made in other editors, including the drag-and-drop editor.
• Manage global styles (color palettes, font families, button formatting, etc) and brand rules. If you want your emails to pull from global styles, set them up in Design Studio > Styles.
• Publish changes from global styles or custom components to every message that references them. Publishing works one email at a time.
• Send an email to your audience. Use the App API to trigger API-triggered broadcasts, one-time sends, and transactional messages. There is no endpoint that triggers automations.

Host images publicly or upload them through the Assets API

All images must be at publicly accessible URLs. Design Studio does not support base64 inline images.

You can host images in a few ways:

• Through your own Content Delivery Network (CDN)
• Through your external editor’s built-in image host
• By uploading files to Customer.io first through the UI or the Assets API and then copying the URL

The Assets endpoints belong to the App API, not the Design Studio API, but they take the same App API Key. Upload the file first, then reference the returned URL in the email content you send to the Design Studio API.

Content best practices

Use our standard component syntax if you want to edit in Design Studio’s UI

We recommend using our standard component syntax so you have full access to our visual editor. This way you can easily make changes to content, formatting, or styling after adding your email. Standard components use extended HTML, similar but not the same to standard HTML tags. For instance, you’d include <x-paragraph> instead of <p> in your email code.

Without our component syntax, you’ll only be able to edit some of the content and styling from the visual editor. You can edit semantic tags like <p> and <img> but need to take an extra step to modify non-semantic tags. Semantic means the name clearly defines the purpose of the element.

Non-semantic tags include <div> and <span>, and you can edit the text only if you add some code. To edit the content of non-semantic tags in the visual editor, wrap the text of these elements in <x-edit-text>. This is also needed to edit text within <table>. Unlike semantic tags, you won’t be able to add CSS styles or classes through the visual editor’s Properties menu.

HTML and CSS best practices

Format your HTML to account for these best practices:

• Escape HTML strings: In request payloads, you’ll send stringified HTML, not raw HTML. Unescaped, raw HTML in a JSON body is the most common cause of 400 Bad Request errors, so this should help reduce failures:
  • All double quotes must be escaped as \"
  • Literal new lines must be replaced with \n (or the HTML must be on a single line).
  • Before sending, either run your HTML through a JSON string escaper tool, or use JSON.stringify() in a browser console: copy(JSON.stringify(yourHTMLString)) to get a properly escaped string ready to paste.
• CSS inlining: Most email clients strip <style> blocks. Inline your CSS before import, or enable Design Studio’s CSS inlining transformer. You can set transformers directly in the API request when creating/updating the email, so you don’t need to do this as a separate step after import.
• Root elements: <x-base> is the root element of Design Studio messages. It replaces <!doctype html>, <html>, <head> and <body> in standard HTML messages and is a container component you can style in the visual editor. For best results, we recommend using it in place of the typical HTML document structure. However, either will work. Just make sure you don’t include both the <x-base> component and <html>.

Dynamic content: liquid personalization and unsubscribe links

Liquid personalization: Replace placeholder text with Customer.io liquid tags like {{customer.first_name}} or {{trigger.order_id}} where you want personalized content. Learn more about personalizing messages with liquid.

Unsubscribe links: Add {% unsubscribe_url %} somewhere in your email. This is required for marketing emails under regulations like CAN-SPAM and GDPR. Customer.io uses this tag to generate an unsubscribe link unique to each recipient and automatically adds a List-Unsubscribe header to your email. Learn more about options for unsubscribe links.

For transactional messages, an unsubscribe link is recommended but not strictly required.