End-to-end guide for embedding personalized product recommendations into emails using the xgen prediction API.
Overview
XGen serves per-user product recommendations as image URLs you can drop straight into email HTML. Each <img> you embed renders a recommended product; each click-through link routes the user to that product on your site.
The flow is:
- Create a container — the recommendation slot configuration.
- Create an email template — defines how each product image is rendered (dimensions, layout, HTML/CSS).
- Attach the email template to the container.
- Embed one prediction URL per product position in your email HTML. Six products = six
<img>tags + six links.
At send time, the prediction endpoint resolves the user, picks the product for that position, and returns the rendered image (or the destination URL for links).
Setup
1. Create a container
A container holds the recommendation configuration (model, collection, ranking rules). Create it in the xgen dashboard under the relevant product area.
Note the container_id — you'll need it for every email URL.
2. Create an email template
In the dashboard, create an email template with:
- Name — internal label.
- Width / Height (px) — pixel dimensions of the rendered product image. These set the size of the
<img>xgen returns. - HTML / CSS — the markup rendered for each product. Use template variables for product fields (name, price, image, etc.).
Optionally, use Choose Product to Preview to paste in any product ID and click Preview Template to verify rendering before going live.
3. Attach the template to the container
On the container's settings page, attach the email template you just created. The container must have an email template attached before the email endpoints will return images.
4. Embed prediction URLs in your email
For each product slot in your email, embed one image URL and one link URL. The index parameter (1-based) identifies the slot; xgen guarantees each index returns a distinct product for that user.
<a
href="https://prediction.xgen.dev/customers/{cst_id}/users/{user_id}/email-link?container_id={container_id}&collection={collection}&index=1"
>
<img
src="https://prediction.xgen.dev/customers/{cst_id}/users/{user_id}/email?container_id={container_id}&collection={collection}&index=1"
/>
</a>
Repeat with index=2, index=3, … for as many products as you want to show.
Substitute the placeholders at email-render time from your ESP's merge fields:
| Placeholder | Source |
|---|---|
{cst_id} |
Your xgen customer ID (constant) |
{user_id} |
The recipient's user ID in your system |
{container_id} |
From step 1 |
{collection} |
Catalog collection (optional, defaults to default) |
{index} |
Slot number, 1-based |
API reference
GET /customers/{cst_id}/users/{user_id}/email
Returns the rendered product image for one slot.
Path params
| Name | Description |
|---|---|
cst_id |
xgen customer ID |
user_id |
Recipient's user ID |
Query params
| Name | Required | Default | Description |
|---|---|---|---|
container_id |
yes | — | Container with an attached email template |
collection |
no | default |
Catalog collection to recommend from |
index |
no | 1 |
1-based slot index; each index returns a distinct product |
Response — image/* rendered from the attached email template at its configured width × height.
GET /customers/{cst_id}/users/{user_id}/email-link
Returns the destination URL for the product at the same slot. Use as the href of the surrounding <a> so the click-through matches the image.
Path and query params are identical to /email. Use the same container_id, collection, and index you used for the image so the link resolves to the same product.
Notes & gotchas
- One template per container. If you want a different template applied you will need to change the original or create a new container.
- Template required.
/emailwill not return a product image if the container has no email template attached. - Width/height are baked in. The image is rendered server-side at the template's dimensions; resizing in the email client may degrade quality.