How to render an email with the Render API

This article shows you how to use the Render API to turn your Email Design System components into email HTML, and then pass that HTML to your ESP.

The Render API builds an email on demand from the components in your EDS. It’s useful for transactional emails, such as order confirmations and password resets. Instead of keeping a copy of the HTML for every template in your ESP, you render each email when you send it. When you change a component in your EDS, every email that uses it picks up the change the next time it’s rendered.

Before you begin

Create an API key with the Renders: Create scope. See How to create an API key.
Find your workspace ID and Email Design System ID. Open the EDS in the app: the address bar shows /workspaces/WORKSPACE_ID/email_design_systems/EDS_ID/.
Know the names of the components and fields you want to use. You can see them in the Component Builder.

Describe the email you want to render

You send the email’s content to the API as JSON. It has the same shape as an email built in the editor:

email_design_system_id: the ID of your EDS.
locale: the locale to render, such as en-US.
brand_profile_id (optional): the ID of a brand profile to render with.
email_content: the email itself:
- subject and preheader: the subject line and preheader text.
- container_component_instance: the field values for your EDS’s container component.
- component_instances: the components in the email, in order. Each one has a unique id (a UUID), the component_name from your EDS, and its field_values.

Content is grouped first by conditional branch, then by locale. If you’re not using conditionals, put everything under null_branch. For example, a subject line looks like this:

subject: {
  branch_content: {
    null_branch: {
      'en-US': 'Your order has shipped',
    },
  },
},

Field values follow the same pattern, with each field’s name and value:

field_values: {
  null_branch: {
    'en-US': {
      header_text: { value: 'Your order has shipped' },
    },
  },
},

Render the email

Send the content in a POST request to https://api.emailshepherd.com/api/v1/workspaces/WORKSPACE_ID/renders. This example uses Node.js:

const apiKey = process.env.EMAILSHEPHERD_API_KEY;
const workspaceId = 123;

const payload = {
  email_design_system_id: 456,
  locale: 'en-US',
  email_content: {
    subject: {
      branch_content: {
        null_branch: { 'en-US': 'Your order has shipped' },
      },
    },
    preheader: {
      branch_content: {
        null_branch: { 'en-US': 'Track your parcel' },
      },
    },
    container_component_instance: {
      id: '7c9e6679-7425-40de-944b-e07fc1f90ae7',
      component_name: 'container_component',
      field_values: {
        null_branch: {
          'en-US': {
            email_background_color: { value: '#ffffff' },
          },
        },
      },
    },
    component_instances: [
      {
        id: 'bd1c1b82-1a7b-4f0f-b079-30c1d4189bed',
        component_name: 'header',
        field_values: {
          null_branch: {
            'en-US': {
              header_text: { value: 'Your order has shipped' },
              header_link_url: { value: 'https://example.com/orders' },
            },
          },
        },
      },
      {
        id: '3f2504e0-4f89-41d3-9a0c-0305e82c3301',
        component_name: 'body',
        field_values: {
          null_branch: {
            'en-US': {
              body: { value: 'Your order is on its way.' },
            },
          },
        },
      },
    ],
  },
};

const response = await fetch(
  `https://api.emailshepherd.com/api/v1/workspaces/${workspaceId}/renders`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(payload),
  },
);

const { html, subject, preheader } = await response.json();

Replace the workspace ID, EDS ID, component names and field names with your own.

The response contains the rendered html, subject and preheader.

Send the email through your ESP

Pass the rendered HTML and subject line to your ESP’s sending API. For example:

await fetch('https://api.your-esp.com/v1/send', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    to: 'customer@example.com',
    subject,
    html,
  }),
});

The request format depends on your ESP, so check its API documentation.

Next steps

For every parameter the Render API accepts, see the Render endpoint in the API reference.