managing-contacts

Mailtrap のコンタクト管理

概要

API リクエストボディを生成する前に： 最新のフィールド名、必須パラメーター、ネストされた構造を確認するには、Contacts OpenAPI specを確認してください。

コンタクトはマーケティング用データベースです。キャンペーンのオーディエンスや関連ワークフロー向けのリスト、セグメント、カスタムフィールド、インポートが含まれます。Contacts APIで作成や更新を自動化でき、CRM や CDP との同期にも利用できます（独自のコード、または Zapier、Make、n8n などのツールを使用します。コンタクトのインポートを参照してください）。

ハードバウンス、迷惑メール報告、送信側の配信停止などの抑制対象は、送信プロダクトで管理され、該当するアドレスへの配信をストリーム上でブロックします。これは、キャンペーンの対象者を決定するマーケティング側のフィルター（セグメント、リストへの登録、同意フラグ）とは別に適用されます。送信側のブロックについては、Suppressionsとスキル sending-emailsを参照してください。

関連スキル： authorizing-api-requests（トークン、環境変数、account_idの解決）、sending-emails（実際の送信方法）。

使用する場面

• プログラムによるコンタクト管理（作成、更新、一括インポート）
• CRM やデータウェアハウスとの同期
• コンタクトリストの整理と CSV のインポート
• オートメーション向けのカスタムフィールドを使ったコンタクトの更新や、カスタムイベントの発火
• オーディエンスの構築に使うセグメントとカスタムフィールド

認証

以下のすべてのエンドポイントには、Authorization: Bearer $MAILTRAP_API_TOKENとパス内の$MAILTRAP_ACCOUNT_IDが必要です。トークンのスコープ、保存方法、GET https://mailtrap.io/api/accountsから$MAILTRAP_ACCOUNT_IDを解決するワンライナーについては、スキルauthorizing-api-requestsを参照してください。

エンドポイント（プレースホルダーを置き換えてください）

アクション	メソッド	URL	参照
コンタクトの作成／取得／更新／削除	various	https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts	コンタクト
一括インポート（非同期ジョブ）	POST	https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/imports	一括インポート
コンタクトリスト	various	https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/lists	コンタクトリスト
カスタムフィールド	various	https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/fields	コンタクトフィールド
カスタムイベント	POST	https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/{contact_identifier}/events	コンタクトイベント
コンタクトのエクスポート	various	https://mailtrap.io/api/accounts/$MAILTRAP_ACCOUNT_ID/contacts/exports	コンタクトのエクスポート

• レート制限（通常）：アカウントごとに60秒あたり200リクエストです。大量に読み込む場合は、一括インポートを優先してください。
• 一括インポートの上限： 1回のインポートリクエストにつき、最大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": "[email protected]",
      "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": "[email protected]", "fields": {"first_name": "John"}, "list_ids_included": [1, 2]},
      {"email": "[email protected]", "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}}'

概念

• リスト — 明示的に定義されたコンタクトのリストです。
• セグメント — 動的なグループです。セグメントを参照してください。
• カスタムフィールド — 名、姓、会員レベルなどのプロパティです。カスタムフィールドを参照してください。
• カスタムイベント — イベントのnameとparamsオブジェクトを指定してPOST .../eventsを実行し、オートメーションで使用します。

CRM と同期

• API： CRM またはデータベースからのリアルタイム同期やスケジュールされた同期に適しています。
• ノーコード： コンタクトのインポート — サードパーティツールに記載されているZapier、Make.com、n8nを利用できます。

キャンペーンのユースケース

コンタクトはマーケティングキャンペーンの基盤です。ここでリスト、同意、属性を適切に管理し、キャンペーンの作成とスケジュール設定については、キャンペーンに記載されている製品機能をご利用ください。

よくある間違い

間違い	対処方法
1件ずつ作成してレート制限に達する	一括読み込みには /contacts/imports を使用します（1リクエストあたり5万件を遵守）。バックオフも行ってください
マーケティング連絡先を送信抑止として扱う	送信ストリームでブロックされた宛先には Suppression を使用します