> This page is part of the [Customer.io documentation](https://docs.customer.io). For the complete index, see [llms.txt](https://docs.customer.io/llms.txt). > Last updated: October 7, 2026 > To take actions in Customer.io from an agent, use the [Customer.io CLI](https://docs.customer.io/ai/cli/get-started.md) or the [MCP server](https://docs.customer.io/ai/mcp/get-started.md). # 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](/integrations/api/app/tag/assets/) 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](/integrations/api/app/tag/send-messages/), so one key covers your whole integration. ## How it works 1. Design your email in your external tool. * Make sure your [asset files](#host-images-publicly-or-upload-them-through-the-assets-api) are publicly hosted or uploaded to your assets library. * Follow the [content best practices](#html-and-css-best-practices) below. 2. [In Workspace settings, create an App API key](https://fly.customer.io/workspaces/last/settings/api_credentials?keyType=app) for authentication. 3. Push the HTML to Customer.io through the [Emails endpoints](/integrations/api/design-studio/tag/emails/). 4. Check the email before you send it: [review](/integrations/api/design-studio/tag/email-testing/reviewEmail/) it for issues, [preview](/integrations/api/design-studio/tag/email-testing/previewEmail/) it with sample data, and [send a test](/integrations/api/design-studio/tag/email-testing/testSendEmail/) to your own inbox. 5. (Optional) [Request inbox previews](/integrations/api/design-studio/tag/email-testing/submitInboxPreview/) to compare how it’d render across email clients. 6. [Link the email](/integrations/api/design-studio/tag/email-email-link-and-publish/linkEmail/) to an automation, broadcast, or transactional message, then [publish](/integrations/api/design-studio/tag/email-email-link-and-publish/publishEmail/) 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](/integrations/api/app/tag/send-messages/). 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](/messaging/design-studio/styles/), set them up in [*Design Studio > Styles*](https://fly.customer.io/workspaces/last/design-studio/global-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](/integrations/api/app/tag/send-messages/) 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](/integrations/api/app/tag/assets/) 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](/messaging/design-studio/reusable/standard-components/) 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 `` instead of `

` 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 `

` and `` 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 `

` and ``, 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 ``](/messaging/design-studio/reusable/standard-components/#style-html-like-standard-components). This is also needed to edit text within ``. 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 `