reach

Hostinger Reach（邮件营销）

Reach API 提供邮件营销能力——管理联系人、为定向营销活动创建细分，以及使用发件人资料。

目录

• 核心概念
• 常见模式
• API 参考
• 最佳实践
• 故障排查
• 参考资料

核心概念

联系人

联系人是营销系统中的邮件收件人。每个联系人都包含基本信息（名字、邮箱、姓氏）和订阅状态。如果启用了双重确认订阅，新联系人会以待确认状态开始，并收到一封确认邮件。

细分

细分根据特定条件（邮箱、姓名、订阅状态、互动指标等）对联系人进行分组。细分支持使用 equals、contains、gte、lte、opened、clicked 等运算符进行复杂筛选。

资料

发件人资料代表用于发送营销活动的邮件身份。每个资料都包含基本信息，并与你的账户关联。

联系人群组

群组是一种组织联系人的方式（已弃用，建议改用细分）。

订阅状态

联系人可以有不同的订阅状态，这些状态决定他们是否接收邮件。在列出联系人时，可以将状态用作筛选条件。

常见模式

创建和管理联系人

# Create a new contact (direct)
curl -X POST "https://developers.hostinger.com/api/reach/v1/contacts" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "John",
    "surname": "Doe",
    "phone": "+15551234567",
    "note": "Met at conference"
  }'

# Create a new contact (scoped to a specific sender profile)
curl -X POST "https://developers.hostinger.com/api/reach/v1/profiles/{profileUuid}/contacts" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "John",
    "surname": "Doe"
  }'

# List contacts (paginated)
curl -X GET "https://developers.hostinger.com/api/reach/v1/contacts?page=1" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

# Filter contacts by subscription status
curl -X GET "https://developers.hostinger.com/api/reach/v1/contacts?subscription_status=active" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

# List contact groups
curl -X GET "https://developers.hostinger.com/api/reach/v1/contacts/groups" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

# Delete a contact
curl -X DELETE "https://developers.hostinger.com/api/reach/v1/contacts/{uuid}" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

Python SDK：

from hostinger_api import Hostinger

client = Hostinger(api_token="YOUR_API_TOKEN")

# List contacts
contacts = client.reach.contacts.list(page=1)
for contact in contacts:
    print(f"{contact.name} <{contact.email}>")

TypeScript SDK：

import { Hostinger } from "hostinger-api-sdk";

const client = new Hostinger({ apiToken: "YOUR_API_TOKEN" });

const contacts = await client.reach.contacts.list({ page: 1 });
for (const contact of contacts) {
  console.log(`${contact.name} <${contact.email}>`);
}

PHP SDK：

use Hostinger\Api\HostingerApi;

$client = new HostingerApi('YOUR_API_TOKEN');

$contacts = $client->reach->contacts->list(['page' => 1]);
foreach ($contacts as $contact) {
    echo "{$contact->name} <{$contact->email}>\n";
}

使用细分

# List all segments
curl -X GET "https://developers.hostinger.com/api/reach/v1/segmentation/segments" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

# Create a segment (e.g., engaged subscribers who opened emails)
curl -X POST "https://developers.hostinger.com/api/reach/v1/segmentation/segments" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engaged Subscribers",
    "logic": "and",
    "conditions": [
      {
        "field": "subscription_status",
        "operator": "equals",
        "value": "active"
      },
      {
        "field": "email_engagement",
        "operator": "opened"
      }
    ]
  }'

# Get segment details
curl -X GET "https://developers.hostinger.com/api/reach/v1/segmentation/segments/{segmentUuid}" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

# List contacts in a segment (paginated)
curl -X GET "https://developers.hostinger.com/api/reach/v1/segmentation/segments/{segmentUuid}/contacts?page=1&per_page=50" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

管理资料

# List all sender profiles
curl -X GET "https://developers.hostinger.com/api/reach/v1/profiles" \
  -H "Authorization: Bearer $HOSTINGER_API_TOKEN"

API 参考

联系人

方法	端点	描述
GET	/api/reach/v1/contacts	列出联系人（分页、可筛选）
POST	/api/reach/v1/contacts	创建联系人（直接）
POST	/api/reach/v1/profiles/{profileUuid}/contacts	创建归属于某个发件人资料的联系人
GET	/api/reach/v1/contacts/groups	列出联系人群组
DELETE	/api/reach/v1/contacts/{uuid}	删除联系人

细分

方法	端点	描述
GET	/api/reach/v1/segmentation/segments	列出所有细分
POST	/api/reach/v1/segmentation/segments	创建新细分
GET	/api/reach/v1/segmentation/segments/{segmentUuid}	获取细分详情
GET	/api/reach/v1/segmentation/segments/{segmentUuid}/contacts	列出细分中的联系人

资料

方法	端点	描述
GET	/api/reach/v1/profiles	列出发件人资料

联系人查询参数

参数	描述
page	页码
group_uuid	按群组 UUID 筛选
subscription_status	按订阅状态筛选

细分条件运算符

运算符	描述
equals / not_equals	精确匹配
contains / not_contains	部分匹配
gte / lte	大于/小于或等于
exists	字段有值
within_last_days / not_within_last_days	日期范围
older_than_days	早于 N 天
opened / not_opened	邮件打开互动
clicked / not_clicked	邮件点击互动
bounced / not_bounced	退信状态
delivered / not_delivered	送达状态
unsubscribed / not_unsubscribed	退订状态

最佳实践

联系人管理

• 使用直接的 POST /contacts 端点进行一般联系人创建；当联系人必须归属于特定发件人资料时，使用 POST /profiles/{profileUuid}/contacts
• 组织联系人时优先使用细分而非联系人群组——群组是旧版功能
• 启用双重确认订阅，以符合邮件营销法规（GDPR、CAN-SPAM）
• 定期清理联系人列表，移除退信和已退订的联系人

细分

• 使用 and 逻辑进行狭窄、精确的定向
• 使用 or 逻辑覆盖更广泛的受众
• 将互动操作符（opened、clicked）与基于时间的操作符结合，用于再互动活动
• 在创建活动之前先创建细分，以预览受众规模

个人资料

• 验证发件人个人资料以提高送达率
• 在各活动中使用一致的发件人身份

故障排除

联系人未收到邮件

• 检查订阅状态 — 联系人可能已取消订阅或处于待确认状态
• 如果启用了双重选择加入，联系人必须先确认其电子邮件
• 验证联系人的电子邮件地址有效且未退信

细分未返回任何联系人

• 验证条件和操作符是否正确
• 检查 logic 字段（and/or）是否符合你的意图
• 确保存在满足所有/任一条件的联系人

创建联系人时出现 422 验证错误

• 缺少必填字段（email 为必填）
• 电子邮件格式无效
• 系统中已存在重复的电子邮件地址

参考

• Hostinger API 文档
• Hostinger API 变更日志
• Python SDK
• TypeScript SDK
• PHP SDK
• CLI 工具