ESP Integration Guide for Hello Retail Product Agents¶

This document describes the requirements for Email Service Providers (ESPs) to integrate with Hello Retail's Product Agents messaging system.

Overview¶

Hello Retail's Product Agents generate personalized marketing messages for e-commerce customers. When a message is ready to send, we push it to your platform via HTTP API. Your platform is responsible for rendering the message content into an email template and delivering it to the recipient.

Customer Setup Flow¶

1. Your customer (the merchant) generates an API key in your platform
2. The merchant adds this API key to their Hello Retail account configuration
3. Hello Retail uses this API key when making requests to your platform on behalf of that merchant

Integration Requirements¶

You need to provide two API endpoints:

1. Send Message API¶

Receives message content from Hello Retail and delivers it to the recipient.

Method: POST

Headers:

Content-Type: application/json
Authorization: <your-auth-scheme> <api-key>

Request Body: See Message Payload Format below.

Expected Response:

{
  "success": true
}

{
  "success": false,
  "error": "Description of what went wrong"
}

2. Permission Check API¶

Verifies whether we are allowed to send messages to a specific recipient. This check happens before we generate the message content, saving computational resources if the recipient cannot receive messages.

Method: GET or POST

Parameters:

• email - The recipient's email address

Headers:

Authorization: <your-auth-scheme> <api-key>

Expected Response:

{
  "canSend": true
}

{
  "canSend": false,
  "reason": "not_subscribed"
}

Configuration¶

Please provide Hello Retail with:

Message Payload Format¶

The payload contains AI-generated email content and product data. All fields should be made available in your template rendering context.

{
  "subject": "...",
  "previewText": "...",
  "headline": "...",
  "body": "...",
  "callToAction": "...",
  "otherProductsTitle": "...",
  "otherProductsText": "...",
  "otherProductsCallToAction": "...",
  "messageType": "REPLENISHMENT_REMINDER",
  "recipient": {
    "email": "customer@example.com"
  },
  "language": "ENGLISH",
  "website": "shop.example.com",
  "inputProduct": { ... },
  "primaryProducts": [ ... ],
  "otherProducts": [ ... ]
}

Content Fields¶

Metadata Fields¶

Product Fields¶

inputProduct is the product that triggered this message — the item the customer previously bought or viewed. You can reference it in your email template to give the message context, for example to remind the customer what they purchased before recommending a replenishment or alternative.

primaryProducts is an array containing the featured product(s) — the main recommendation(s) in the email.

otherProducts is an array of secondary recommended products (0–6 products).

Each product object contains: