Mailtrap Managing Contacts

管理 Mailtrap 联系人

概述

在生成 API 请求体之前： 查阅 Contacts OpenAPI 规范 以获取当前字段名称、必需参数和嵌套结构。

联系人是营销数据库：列表、细分、自定义字段和导入，服务于营销活动受众及相关工作流。Contacts API 可自动化创建/更新联系人，并可对接 CRM 或 CDP 同步（由你的代码或 Zapier、Make、n8n 等工具实现——参见导入联系人）。

抑制列表（硬退信、垃圾邮件投诉、发送端的退订）位于发送产品中，会阻止这些地址在你的流上的投递。这与决定谁有资格接收营销活动的营销过滤器（细分、列表成员资格、同意标记）是分开应用的。关于发送端的阻止，参见抑制列表和 mailtrap-sending-emails。

相关技能： mailtrap-sending-emails（实时发送路径）。

何时使用

• 编程式联系人管理（创建、更新、批量导入）
• 与 CRM 或数据仓库同步
• 联系人列表清理和 CSV 导入
• 使用自定义字段更新联系人或为自动化触发自定义事件
• 细分和自定义字段用于受众构建

授权

以下所有端点需要 Authorization: Bearer $MAILTRAP_API_TOKEN 以及路径中的 $MAILTRAP_ACCOUNT_ID。通过 GET https://mailtrap.io/api/accounts 解析 $MAILTRAP_ACCOUNT_ID，并将令牌存储在环境变量或密钥管理器中。

端点（替换占位符）

• 速率限制（典型值）：每个账户每 60 秒 200 个请求——大量负载时请使用批量导入。
• 批量导入限制： 每次导入请求最多 50,000 个联系人（异步任务）；使用 GET .../contacts/imports/{import_id} 轮询导入状态。参见批量导入。

示例（curl）

创建单个联系人（含自定义字段）

curl -X POST "https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts" \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "contact": {
      "email": "john.smith@example.com",
      "fields": {"first_name": "John", "last_name": "Smith", "company": "Example Inc"},
      "list_ids": [1, 2, 3]
    }
  }'

批量导入（联系人数组）

curl -X POST "https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/imports" \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "contacts": [
      {"email": "user1@example.com", "fields": {"first_name": "John"}, "list_ids_included": [1, 2]},
      {"email": "user2@example.com", "fields": {"first_name": "Jane"}, "list_ids_included": [1]}
    ]
  }'

自定义事件（事件名称 + 载荷）

curl -X POST "https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/{contact_identifier}/events" \
  -H "Authorization: Bearer $MAILTRAP_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name": "UserLogin", "params": {"user_id": 101, "is_active": true}}'

概念

• 列表 — 显式定义的联系人列表。
• 细分 — 动态分组；参见细分。
• 自定义字段 — 如名字、姓氏或会员等级等属性；参见自定义字段。
• 自定义事件 — 通过 POST .../events 发送事件 name 和 params 对象，用于自动化。

CRM 与同步

• API： 适用于从 CRM 或数据库进行实时或定时同步。
• 无代码： Zapier、Make.com、n8n，参见导入联系人 – 第三方工具。

营销活动用例

联系人驱动营销活动：你在此维护干净的列表、同意状态和属性；营销活动创作和排期是产品功能，文档参见营销活动。

常见错误

限制

• 联系人 API 结构可能变更；生成请求体前请查阅 Mailtrap 当前的 OpenAPI 规范。