API Reference

联系人数据导出 API 文档

为 BI 系统或其他数据分析平台提供分页拉取曼巴系统中所有联系人及其标签、国家、订阅状态的接口

📋 基础信息

适用场景

当您的公司需要将 MambaSMS 系统中的全部联系人数据（包含标签、国家、订阅状态等）导入到 BI 平台（如 Tableau、Power BI、Metabase 等）或自有数据仓库时，通过本接口分页拉取数据。

核心能力：

  • 全量联系人导出（支持分页）
  • 支持按创建时间范围筛选（created_at_start / created_at_end）
  • 每条联系人包含：基本信息 + 分类标签 + 平台标签 + 订阅状态
  • 使用 API Key 认证，与现有 Events API 保持一致

接口地址

GET /api/v1/audience

🔑 认证方式

API 服务地址

  • 生产环境： https://front-api.mambasms.com
  • 测试环境： https://olapapi.mambasend.com

获取 API Token

  1. 登录 MambaSMS 后台
  2. 进入 店铺设置 → API 密钥
  3. 复制 Security Key（格式：shop_xxxxxxxx）

请求头

X-Mamba-Access-Token: shop_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

📄 接口详细说明

请求参数

参数类型必填默认值说明
pageInteger否1页码，从 第 1 页 开始
page_sizeInteger否1000每页条数，最大 5000
created_at_startLong否-创建时间起始（Unix 秒），闭区间 >=。筛选在此时间及之后创建的联系人
created_at_endLong否-创建时间截止（Unix 秒），闭区间 <=。筛选在此时间及之前创建的联系人

时间筛选说明：created_at_start 和 created_at_end 均为可选，可单独使用或组合使用。两者都传时表示闭区间范围 [created_at_start, created_at_end]。
筛选的是 mb_audience.create_at_time（10 位 Unix 时间戳），即联系人首次进入系统的时间。
常用场景：每天定时拉取前一天新增的联系人，只需传 created_at_start=昨日0点 + created_at_end=今日0点。

分页说明

  • 默认第一页，page=1，不是 0-based
  • 首次调用不带 page 参数即可拿到第一页 + 总条数 + 总页数
  • 拿到 total_pages 后，循环 page=1 到 page=total_pages 即可拉全
  • 每页最多 5000 条，超出报 400 错误

请求示例

# 第一页（默认）
curl -X GET "https://front-api.mambasms.com/api/v1/audience" \
  -H "X-Mamba-Access-Token: shop_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# 指定页码和每页条数
curl -X GET "https://front-api.mambasms.com/api/v1/audience?page=2&page_size=500" \
  -H "X-Mamba-Access-Token: shop_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# 按时间范围筛选（2024-01-01 到 2024-12-31 创建的联系人）
curl -X GET "https://front-api.mambasms.com/api/v1/audience?page=1&page_size=1000&created_at_start=1704067200&created_at_end=1735689599" \
  -H "X-Mamba-Access-Token: shop_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# 只查某天之后创建的（常用于增量同步）
curl -X GET "https://front-api.mambasms.com/api/v1/audience?page=1&page_size=1000&created_at_start=1753315200" \
  -H "X-Mamba-Access-Token: shop_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

响应格式

{
  "page": 1,
  "page_size": 1000,
  "total_count": 52341,
  "total_pages": 53,
  "data": [
    {
      "id": "7432512345678901234",
      "origin_id": "shopify_cust_998877",
      "email": "[email protected]",
      "phone": "+1234567890",
      "first_name": "John",
      "last_name": "Doe",
      "country": "US",
      "country_name": "United States",
      "city": "New York",
      "gender": "male",
      "birth_date": "1990-06-15",
      "email_subscribed": true,
      "sms_subscribed": false,
      "created_at": "2024-03-10 08:30:00",
      "tags": [
        { "category": "会员等级", "value": "VIP" },
        { "category": "来源渠道", "value": "官网" },
        { "category": "消费偏好", "value": "高客单" }
      ],
      "platform_tags": ["Onelap", "VE200"]
    },
    {
      "id": "7432512345678901235",
      "origin_id": "shopify_cust_112233",
      "email": "[email protected]",
      "phone": "+19876543210",
      "first_name": "Jane",
      "last_name": "Smith",
      "country": "GB",
      "country_name": "United Kingdom",
      "city": "London",
      "gender": "female",
      "birth_date": "",
      "email_subscribed": true,
      "sms_subscribed": true,
      "created_at": "2024-06-01 12:00:00",
      "tags": [],
      "platform_tags": []
    }
  ]
}

响应字段说明

分页字段：

字段类型说明
pageInteger当前页码
page_sizeInteger当前每页条数
total_countInteger符合条件的总记录数
total_pagesInteger总页数（total_count / page_size 向上取整）

联系人字段（data 数组中的每一条）：

字段类型说明
idString曼巴系统内部联系人 ID
origin_idString平台侧原始 ID（如 Shopify Customer ID）
emailString邮箱地址
phoneString手机号（带国际区号）
first_nameString名
last_nameString姓
countryString国家编码（ISO 3166-1 alpha-2，如 US / CN / GB）
country_nameString国家中文/英文名称
cityString城市
genderString性别（male / female）
birth_dateString生日（yyyy-MM-dd 格式，无数据为空字符串）
email_subscribedBoolean是否已订阅邮件
sms_subscribedBoolean是否已订阅短信
created_atString联系人创建时间（yyyy-MM-dd HH:mm:ss）
tagsArray分类标签列表（{category: 标签分类, value: 标签值}）
platform_tagsArray平台标签列表（字符串数组，来自 Shopify 等平台的原始 tags）

空页响应

当请求的页码超出范围时，返回空数组：

{
  "page": 99,
  "page_size": 1000,
  "total_count": 52341,
  "total_pages": 53,
  "data": []
}

⚠️ 重要注意事项

1. 频率限制

建议请求间隔 ≥ 1 秒，避免对数据库造成压力。

2. 数据一致性

  • 分页拉取期间可能有新数据写入，同一次全量同步中不同页的数据可能不是同一时刻的快照
  • 如需严格一致性，建议在业务低峰期进行全量同步

3. 标签体系说明

标签分两套：

标签类型响应字段来源示例
分类标签tagsEvents API tag_value 或 BM 后台手动打标{"category":"会员等级","value":"VIP"}
平台标签platform_tagsShopify 等平台原生 Customer Tags["Onelap","VE200"]

4. 错误码

HTTP 状态码说明处理方式
200成功-
400page_size 超过 5000，或 created_at_end < created_at_start检查参数
401Token 无效或未传检查 X-Mamba-Access-Token
429请求过于频繁降低频率，等待后重试
500服务器内部错误重试，如持续报错请联系技术支持

🚀 快速开始

完整同步脚本（bash）

#!/bin/bash
BASE_URL="https://front-api.mambasms.com"
TOKEN="shop_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
OUTPUT_DIR="./mamba_audience_export"
PAGE_SIZE=1000

mkdir -p "$OUTPUT_DIR"

# 1. 先拉第一页，获取总页数
echo "正在获取第一页..."
FIRST_PAGE=$(curl -s -X GET "${BASE_URL}/api/v1/audience?page=1&page_size=${PAGE_SIZE}" \
  -H "X-Mamba-Access-Token: ${TOKEN}")
echo "$FIRST_PAGE" > "${OUTPUT_DIR}/page_1.json"

TOTAL_PAGES=$(echo "$FIRST_PAGE" | jq -r '.total_pages')
TOTAL_COUNT=$(echo "$FIRST_PAGE" | jq -r '.total_count')
echo "总联系人: ${TOTAL_COUNT}, 总页数: ${TOTAL_PAGES}"

# 2. 拉取剩余页
for ((page=2; page<=TOTAL_PAGES; page++)); do
  echo "正在拉取第 ${page}/${TOTAL_PAGES} 页..."
  curl -s -X GET "${BASE_URL}/api/v1/audience?page=${page}&page_size=${PAGE_SIZE}" \
    -H "X-Mamba-Access-Token: ${TOKEN}" > "${OUTPUT_DIR}/page_${page}.json"
  sleep 1
done

echo "同步完成！数据保存在 ${OUTPUT_DIR}/"

增量同步脚本（bash）

每天拉取前一天新增的联系人：

#!/bin/bash
BASE_URL="https://front-api.mambasms.com"
TOKEN="shop_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
OUTPUT_DIR="./mamba_audience_export"
PAGE_SIZE=1000

mkdir -p "$OUTPUT_DIR"

# 计算昨天 0 点和今天 0 点的 Unix 时间戳
TODAY_START=$(date -d "today 00:00:00" +%s)
YESTERDAY_START=$(date -d "yesterday 00:00:00" +%s)
DATE_STR=$(date -d "yesterday" +%Y%m%d)

echo "拉取 ${DATE_STR} 新增的联系人..."

# 1. 先拉第一页，获取总页数
FIRST_PAGE=$(curl -s -X GET \
  "${BASE_URL}/api/v1/audience?page=1&page_size=${PAGE_SIZE}&created_at_start=${YESTERDAY_START}&created_at_end=${TODAY_START}" \
  -H "X-Mamba-Access-Token: ${TOKEN}")
echo "$FIRST_PAGE" > "${OUTPUT_DIR}/daily_${DATE_STR}_page_1.json"

TOTAL_PAGES=$(echo "$FIRST_PAGE" | jq -r '.data.total_pages')
TOTAL_COUNT=$(echo "$FIRST_PAGE" | jq -r '.data.total_count')
echo "${DATE_STR} 新增联系人: ${TOTAL_COUNT}, 总页数: ${TOTAL_PAGES}"

# 2. 拉取剩余页
for ((page=2; page<=TOTAL_PAGES; page++)); do
  echo "正在拉取第 ${page}/${TOTAL_PAGES} 页..."
  curl -s -X GET \
    "${BASE_URL}/api/v1/audience?page=${page}&page_size=${PAGE_SIZE}&created_at_start=${YESTERDAY_START}&created_at_end=${TODAY_START}" \
    -H "X-Mamba-Access-Token: ${TOKEN}" > "${OUTPUT_DIR}/daily_${DATE_STR}_page_${page}.json"
  sleep 1
done

echo "${DATE_STR} 增量同步完成！数据保存在 ${OUTPUT_DIR}/"

Updated 20 days ago

Did this page help you?

Updated 20 days ago

Did this page help you?