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 (2xx):

{
  "success": true
}

Error (4xx/5xx):

{
  "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:

Can send:

{
  "canSend": true
}

Cannot send:

{
  "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": "en",
  "website": "https://shop.example.com",
  "inputProduct": { ... },
  "primaryProducts": [ ... ],
  "otherProducts": [ ... ]
}

Content Fields¶

Metadata Fields¶

Product Fields¶

inputProduct is the product that triggered the message (what the customer previously bought or viewed).

primaryProducts is an array containing the featured product(s).

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

Each product object contains: