Newsletter Content¶

Read, write and render the designs behind Newsletter Content: the templates Hello Retail turns into the personalized product images a newsletter embeds.

Hello Retail renders a Newsletter Content design server-side into a JPEG image, one image per product, called a tile, and the newsletter embeds those images. The recipient never receives the HTML and no email client ever lays it out. Text, prices, buttons and badges all become baked pixels inside a picture of a fixed size, so nothing reflows, nothing wraps onto extra lines the box doesn't have, and anything that doesn't fit is clipped. That one fact shapes everything else on this page.

The template language is covered in the Newsletter Content templates guide. newsletterContent_getRenderingInfo returns the rest: the CSS the renderer supports, the fonts installed on it, and your website's own product variables.

newsletterContent_renderDesign renders a design, saved or unsaved, against real products from the website and returns the resulting images, so your assistant can look at what it produced instead of reasoning about the markup. A template whose source reads perfectly can still clip a product title mid-word or push a price off the canvas, and that's only visible in the render.

Designs have no draft and live states. A save is immediately the design's only version, so these tools are the exception to the rule that MCP edits land in a draft. What a save doesn't do is rewrite newsletters that are already out. See what an edit reaches, and when below.

Show me the rendering info for Newsletter Content on my website, then explain what I can and cannot use in a design.

List the Newsletter Content starter templates, then show me the source of the Side-by-side one.

Render Newsletter Content design <DESIGN ID> against my two longest product titles and tell me whether anything is clipped.

Create a 300x350 Newsletter Content design for my website based on the Simple starter template.

Add markers to Newsletter Content design <DESIGN ID> so the button colour and label can be changed from the dashboard.

Copy Newsletter Content design <DESIGN ID>, make the sale badge larger in the copy, and render it.

What an edit reaches, and when¶

Saving a design never rewrites the newsletters that have already gone out, and it reaches a website's campaigns at different moments depending on the campaign type:

Two consequences worth being deliberate about:

• Tile images are fetched when the recipient opens the mail. So wherever an edit does reach a campaign, it also changes the pictures in mail already sitting in inboxes.
• There's no undo. Read the design with newsletterContent_getDesign before you change it, which leaves you the old template to write back, or work on a copy from newsletterContent_copyDesign and leave the original untouched.

newsletterContent_listDesigns¶

List the Newsletter Content designs of a customer website using Hello Retail. A design is the template one product tile is rendered from; a newsletter embeds one image per product. Returns id, name, lifecycle state, the design's width x height in CSS pixels and its rendering size. Only designs in state LIVE can be picked in the campaign editor. The others are listed so you can see they exist, not so you can point campaigns at them. Use the id with newsletterContent_getDesign, newsletterContent_updateDesign or newsletterContent_renderDesign.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "newsletterContent_listDesigns",
    "arguments": {
      "websiteUuid": "<string>"
    }
  }
}

{
  "designs": [
    {
      "id": "<string>",
      "name": "<string>",
      "state": "LIVE",
      "width": 0,
      "height": 0,
      "renderingSize": "X2",
      "createdAt": "<string>",
      "usableInCampaigns": true
    }
  ]
}

newsletterContent_getDesign¶

Retrieve one Newsletter Content design of a customer website using Hello Retail, including its full Liquid/HTML template. Use this before newsletterContent_updateDesign to read the current state of the design. Hello Retail rasterises the template server-side into a JPEG per product, so read newsletterContent_getRenderingInfo before you change it.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "newsletterContent_getDesign",
    "arguments": {
      "websiteUuid": "<string>",
      "designId": "<string>"
    }
  }
}

{
  "design": {
    "id": "<string>",
    "name": "<string>",
    "state": "LIVE",
    "width": 0,
    "height": 0,
    "renderingSize": "X2",
    "createdAt": "<string>",
    "usableInCampaigns": true
  },
  "template": "<string>"
}

newsletterContent_getRenderingInfo¶

Everything you need to know before writing or editing a Newsletter Content design for a customer website using Hello Retail. Read it first: a newsletter design won't behave like a web page.

The tool returns the concrete facts for the website: the renderer and what CSS it does and doesn't support, the accepted pixel dimensions, the retina multiplier, the fonts actually installed on the render host (a font that is not in this list silently falls back), the Liquid filters available, the design-marker syntax that turns a template variable into a form control in the customer's dashboard, and the product variables sampled from a real product on this website, including its website-specific extraData keys. Those keys are the ones no assistant can guess, because they come from the customer's own product feed.

The template language is documented at greater length in the Managed Templates guide, the Newsletter Content templates guide and the custom Liquid filters reference.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "newsletterContent_getRenderingInfo",
    "arguments": {
      "websiteUuid": "<string>"
    }
  }
}

{
  "renderer": "<string>",
  "outputFormat": "<string>",
  "minDimensionPx": 10,
  "maxDimensionPx": 1000,
  "defaultRenderingSize": "X2",
  "retinaPixelMultiplier": 2,
  "notSupported": ["<string>"],
  "layoutRules": ["<string>"],
  "availableFonts": ["<string>"],
  "liquidFilters": ["<string>"],
  "designMarkers": [
    {
      "syntax": "<string>",
      "description": "<string>"
    }
  ],
  "productVariablesSampledFrom": "<string>",
  "productVariables": ["product.title", "product.price", "product.extraData.<string>"]
}

newsletterContent_listStarterTemplates¶

List the built-in starter templates a Newsletter Content design can be based on. These are the same starting points the dashboard's New design page offers, and each one is a worked example of the idiom that actually renders: table, float and absolute layout, fixed-height overflow-hidden text boxes, design markers for the tunable values, and a sale and full-price branch. Read one with newsletterContent_getStarterTemplate before writing a design from scratch. The width and height listed here are the aspect ratio the template was authored for. The names are the newsletter platform layouts they suit; the Mailchimp ones size for 2, 3 or 4 tiles per row.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "newsletterContent_listStarterTemplates",
    "arguments": {
      "websiteUuid": "<string>"
    }
  }
}

{
  "starterTemplates": [
    {
      "name": "<string>",
      "width": 0,
      "height": 0
    }
  ]
}

newsletterContent_getStarterTemplate¶

Retrieve the full Liquid/HTML source of one built-in starter template, plus the width and height it was authored for. Use newsletterContent_listStarterTemplates to find the names. Copy it into newsletterContent_createDesign, adjusting name, width and height, rather than writing a design from a blank page: the starters show the CSS 2.1 layout idiom, the fixed-height clipping boxes and the design-marker syntax that the renderer and the dashboard both expect.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "newsletterContent_getStarterTemplate",
    "arguments": {
      "websiteUuid": "<string>",
      "name": "<string>"
    }
  }
}

{
  "name": "<string>",
  "width": 0,
  "height": 0,
  "template": "<string>"
}

newsletterContent_renderDesign¶

Render a Newsletter Content design to real product tiles and return the resulting images, so you can see what the design actually produces. Persists nothing, so use it to check your work before and after saving.

Always render before newsletterContent_createDesign or newsletterContent_updateDesign. The output is a fixed-size JPEG with no reflow, so the failures that matter are invisible in the source: a product title clipped mid-word, a price pushed out of the box, a badge overlapping the image, an empty band where a longer title pushed the button off the canvas. Look at the returned image and check the whole canvas is used and nothing is cut off. Render again with the longest and shortest product titles you can find (productUrls). A design that only fits the average product is a design that clips.

Pass designId to render a saved design, or template plus width and height to render a draft you have not saved. Pass both to render a saved design with one field replaced, which is how you verify an edit before writing it. The response also carries the Liquid parse error (line, character, message) if the template doesn't parse, and reports per tile whether an image failed to load. A tile whose images don't all load fails outright, and at send time that product is skipped and replaced with another one.

Alongside the JSON below, the response carries one image per tile that rendered, in the same order as the tiles array. renderedWidthPx and renderedHeightPx are the pixel size of those images, which is the design's box multiplied by the retina factor.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "newsletterContent_renderDesign",
    "arguments": {
      "websiteUuid": "<string>",
      "designId": "<string>",
      "productUrls": ["<string>", "<string>"]
    }
  }
}

{
  "designWidthPx": 0,
  "designHeightPx": 0,
  "renderedWidthPx": 0,
  "renderedHeightPx": 0,
  "renderingSize": "X2",
  "liquidError": null,
  "tiles": [
    {
      "productUrl": "<string>",
      "productTitle": "<string>",
      "onSale": true,
      "rendered": true,
      "error": null
    },
    {
      "productUrl": "<string>",
      "productTitle": "<string>",
      "onSale": false,
      "rendered": false,
      "error": "<string>"
    }
  ],
  "unresolvedProductUrls": []
}

newsletterContent_createDesign¶

Create a new Newsletter Content design for a customer website using Hello Retail. The design is created LIVE, so it is immediately selectable in the campaign editor's design picker; creating it does not change any existing campaign.

width and height are the design's size in CSS pixels and they are the only size it will ever have: the template is rasterised into an image of exactly this box, and everything that doesn't fit is clipped, because there's no browser and therefore no reflow. Author every dimension in these 1x pixels. The renderer doubles them for retina on your behalf, so don't double anything yourself.

Render the template with newsletterContent_renderDesign first and look at the image. Read newsletterContent_getRenderingInfo for the supported CSS, the installed fonts and this website's product variables, and newsletterContent_getStarterTemplate for a template that is known to render. Uploading image assets for a design is a dashboard action (there's no MCP tool for it), so reference images by absolute https URL, or by asset:// only for files the design already has.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "newsletterContent_createDesign",
    "arguments": {
      "websiteUuid": "<string>",
      "name": "<string>",
      "width": 300,
      "height": 350,
      "template": "<string>"
    }
  }
}

{
  "design": {
    "id": "<string>",
    "name": "<string>",
    "state": "LIVE",
    "width": 0,
    "height": 0,
    "renderingSize": "X2",
    "createdAt": "<string>",
    "usableInCampaigns": true
  },
  "template": "<string>"
}

newsletterContent_updateDesign¶

Update a Newsletter Content design of a customer website using Hello Retail. Updates are partial: omitted fields are left unchanged, but at least one must be provided. Read the design with newsletterContent_getDesign and render your new template with newsletterContent_renderDesign before saving. The output is a fixed-size image, so clipped text and images that fail to load are invisible in the source and obvious in the render.

An archived design cannot be edited; copy it with newsletterContent_copyDesign to get an editable one. The rare design Hello Retail staff have configured to render at 1x instead of the standard 2x retina size is also refused — it can be read and rendered, but changes to it are made in My Hello Retail.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "newsletterContent_updateDesign",
    "arguments": {
      "websiteUuid": "<string>",
      "designId": "<string>",
      "template": "<string>"
    }
  }
}

{
  "design": {
    "id": "<string>",
    "name": "<string>",
    "state": "LIVE",
    "width": 0,
    "height": 0,
    "renderingSize": "X2",
    "createdAt": "<string>",
    "usableInCampaigns": true
  },
  "template": "<string>"
}

newsletterContent_copyDesign¶

Copy a Newsletter Content design into a new, independent design on the same customer website. The copy starts from the source's template and dimensions but gets its own id, so it can be edited without touching the original or any campaign using it. Its uploaded image assets are copied too, so asset:// references in the template keep resolving. The copy is created LIVE and selectable in the campaign editor.

This is the safe way to change a design that live campaigns already render: copy it, edit and render the copy, then point the campaign at the copy in the dashboard, instead of editing the original and having the change reach campaigns at a moment you don't control. Copying is also the way to get an editable version of an archived design. Use newsletterContent_listDesigns to find the source id.

The rare design Hello Retail staff have configured to render at 1x instead of the standard 2x retina size can't be copied, because the copy would inherit that rendering size. Those designs stay managed in My Hello Retail.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "newsletterContent_copyDesign",
    "arguments": {
      "websiteUuid": "<string>",
      "sourceDesignId": "<string>",
      "name": "<string>"
    }
  }
}

{
  "copy": {
    "design": {
      "id": "<string>",
      "name": "<string>",
      "state": "LIVE",
      "width": 0,
      "height": 0,
      "renderingSize": "X2",
      "createdAt": "<string>",
      "usableInCampaigns": true
    },
    "template": "<string>"
  },
  "sourceDesignId": "<string>"
}