Mailchimp APIで会員制システムとアカウント連携してみた

こんにちは。ソーイ株式会社 髙﨑です。

本記事では、会員制システム（Laravel）と Mailchimp を連携し、コンタクトの取得・追加/更新・削除・タグ付与を実装した手順を紹介します。
会員管理とメール配信基盤の連携を検討している方の参考になれば幸いです。

目次

• 連携フロー
• Mailchimp準備
• 連携実装
• 感想

連携フロー

はじめに、Mailchimp との連携フローについて説明します。
Mailchimpでは、配信対象のユーザーをコンタクト、コンタクトの集まりをAudienceと言います。
この記事では、上記に則ってMailchimp側アカウントのことをコンタクトと表記します。
開発システムにて、会員登録後Mailchimpにもコンタクト（アカウント）が作成されます。
Mailchimp には、以下の情報を連携します。

• メールアドレス
• 氏名
• タグ

また、会員情報の更新や削除が行われた場合には、その内容を Mailchimp 側のコンタクトにも反映するようにしています。

準備

Mailchimp の管理画面から
Account & billing → Extras → API keys
へ遷移します。

「Your API Keys」セクションにて、「Create A Key」をクリックします。

次にキー名を入力して API キーを作成します。

作成直後に API キーが表示されるため、必ずコピーして保管してください。

※注意点
API キーは 一度画面を離れると再表示・再コピーができません。
コピーし忘れた場合は、API キーを再生成する必要があります。

生成したキー、サーバー、リストIDをシステムの.envファイルに設定すれば準備完了です

#.envファイル
MAILCHIMP_API_KEY=APIキー
MAILCHIMP_API_SERVER=サーバー
MAILCHIMP_LIST_ID=リストID

最後にMailchimpのクライアントライブラリをインストールします。（今回はv3を利用します。）

composer require mailchimp/marketing

以上で準備は完了です。

連携実装

ここからは、システム側の Mailchimp 連携実装について説明します。

今回は以下の機能を実装するため、計 5 種類の API を利用します。

• コンタクトの取得
• コンタクトの追加
• コンタクトの更新
• コンタクトの削除
• タグの付与

コンタクトの取得

まず、メールアドレスからMailchimpコンタクトを取得する　getContactByEmail メソッドを実装します。

/**
 * メールアドレスから Mailchimp のコンタクト情報を取得する
 *
 * @param  string  $email
 * @return array|null  コンタクト情報（取得できない場合は null）
 */
public static function getContactByEmail(string $email): ?array
{
    $mailchimp = new \MailchimpMarketing\ApiClient;
    $mailchimp->setConfig([
        'apiKey' => env('MAILCHIMP_API_KEY'),
        'server' => env('MAILCHIMP_API_SERVER'),
    ]);
    $list_id = env('MAILCHIMP_LIST_ID');

    // subscriber_hash は lowercase(email) の MD5
    $subscriberHash = md5(strtolower($email));

    try {
        $member = $mailchimp->lists->getListMember($listId, $subscriberHash);

        if ($member) {
            return [
                'email_address'      => $member->email_address ?? null,
                'status'             => $member->status ?? null,
                'unsubscribe_reason' => $member->status === 'unsubscribed'
                    ? ($member->unsubscribe_reason ?? null)
                    : null,
                'id'                 => $member->id ?? null,
                'contact_id'         => $member->contact_id ?? null,
                'unique_email_id'    => $member->unique_email_id ?? null,
                'web_id'             => $member->web_id ?? null,
                'merge_fields'       => $member->merge_fields ?? (object) [],
                'tags'               => $member->tags ?? [],
            ];
        }
        
        \Log::error(
            'Mailchimp SDK returned null member',
            ['email' => $email]
        );
    } catch (\Throwable $e) {
        // エラーログ
        \Log::error(
            'Mailchimp SDK failed while fetching member',
            [
                'email' => $email,
                'error' => $e->getMessage(),
            ]
        );
    }

    return null;
}

getListMemberAPIを用いて、コンタクトを取得します。
未登録のメールアドレスを指定した場合、Mailchimp API は 404 エラーを返すため、例外処理でハンドリングしています

コンタクトの追加・更新

次に、Mailchimp コンタクトの 追加・更新 を行う updateOrCreate メソッドを実装します

/**
 * Mailchimpにcontactを追加
 *
 * @param  mixed       $user           ユーザーモデル
 */
public static function updateOrCreate($user)
{
    try {
        // Mailchimp SDK クライアント初期化
        $mailchimp = new \MailchimpMarketing\ApiClient();
        $mailchimp->setConfig([
            'apiKey' => env('MAILCHIMP_API_KEY'),
            'server' => env('MAILCHIMP_API_SERVER'), // 例: "us1"
        ]);

        $listId = env('MAILCHIMP_LIST_ID');

        // Audience に登録するデータ（merge_fields は Mailchimp 側で事前定義が必要）
        $params = [
            'email_address' => $user->email,
            'status' => 'subscribed', // subscribed（購読状態）、unsubscribed（非購読状態）
            'merge_fields' => [
                'FNAME'    => $user->first_name,
                'LNAME'    => $user->last_name,
            ],
        ];

        // setListMember は「作成または更新（Upsert）」として使える
        // subscriber_hash は "lowercase(email)" の MD5 を使うのが推奨
        $mailchimp->lists->setListMember(
            $listId,
            md5(strtolower($user->email)),
            $params
        );

        return false;
    } catch (\Throwable $t) {
        // エラーログ
        Log::error(sprintf(
            'Mailchimp::updateOrCreate failed. : #%s | %s',
            $user->id,
            $t->getMessage()
        ));
    }

    return false;
}

setListMember API を利用することで、

• 対象のメールアドレスが存在しない場合は 新規作成
• すでに存在する場合は 更新

という処理を、1 つの API で実現できます。

コンタクトの削除

会員削除時に Mailchimpコンタクトを削除する処理を実装します。

/**
 * Mailchimp Audience（List）からコンタクトを削除する
 *
 * @param  string  $email  削除対象のメールアドレス
 * @return bool    true: 連携対象外 / false: 処理実行（成功/失敗はログ参照）
 */
public static function delete($email)
{
    try {
        // Mailchimp SDK クライアント初期化
        $mailchimp = new \MailchimpMarketing\ApiClient();
        $mailchimp->setConfig([
            'apiKey' => env('MAILCHIMP_API_KEY'),
            'server' => env('MAILCHIMP_API_SERVER'), // 例: "us1"
        ]);

        $listId = env('MAILCHIMP_LIST_ID');

        // subscriber_hash は "lowercase(email)" の MD5 が推奨
        $subscriberHash = md5(strtolower($email));

        // Audience からコンタクトを削除
        $mailchimp->lists->deleteListMember(
            $listId,
            $subscriberHash
        );

        return false;
    } catch (\Throwable $t) {
        // エラーログ
        Log::error(sprintf(
            'Mailchimp::delete failed. email:#%s | %s',
            $email,
            $t->getMessage()
        ));
    }

    return false;
}

deleteListMember を使用することで、Mailchimp 上から コンタクトを削除できます。

Mailchimp のコンタクト削除について

Mailchimp のコンタクトには、以下の 2 種類の削除状態があります。

• アーカイブ
• 永久削除

アーカイブ状態では、削除したメールアドレスを再登録すると 別のコンタクトとして作成されます。
一方、永久削除を行うと、同じメールアドレスでは 再登録ができなくなります。

本実装で使用している deleteListMember は、アーカイブ状態となります。

タグの付与

最後に、Mailchimpコンタクトにタグを付与する処理を実装します。

/**
 * Mailchimp のタグを更新する
 * - 既存タグを inactive（解除）し、ユーザーが持つタグを active（付与）する
 * @param  mixed  $user
 */
public static function updateTags($email)
{
    try {
        // Mailchimp SDK クライアント初期化
        $mailchimp = new \MailchimpMarketing\ApiClient();
        $mailchimp->setConfig([
            'apiKey' => env('MAILCHIMP_API_KEY'),
            'server' => env('MAILCHIMP_API_SERVER'), // 例: "us1"
        ]);

        $listId = env('MAILCHIMP_LIST_ID');
        $params = [];

        // subscriber_hash は "lowercase(email)" の MD5 が推奨
        $subscriberHash = md5(strtolower($email));

        // 1) 既存タグを inactive（解除）にする（留学関連タグは除外）
        foreach ($member->tags as $tag) {
            $params[] = ['name' => $tag->name, 'status' => 'inactive'];
        }

        // 2) ユーザーが持つタグを active（付与）として追加
        // 例: [['status' => 'active'], ...]
        $userTags = $user->getMailchimpTags();
        $params   = array_merge($params, $userTags);

        // 3) タグを一括更新
        $mailchimp->lists->updateListMemberTags(
            $listId,
            $userMailchimp->contact_id,
            ['tags' => $params]
        );

        return true;
    } catch (\Throwable $t) {
        // エラーログ
        Log::error(sprintf(
            'MailchimpApiClient::updateTags failed. : #%s | %s',
            $user->id,
            $t->getMessage()
        ));

        return false;
    }
}

タグ付与 API は 既存のタグも含めて上書きされる仕様のため、
現在付与されているタグを一度取得し、新しいタグと合わせて再付与する形で実装しています。

タグ名の制限について

Mailchimp API からタグを付与する際、以下の制限があります。

• 日本語、英数字、記号、空白が利用可能
• 日本語＋英字の混在タグは付与不可（例：テストtest）
• タグ名の最大文字数は 100 文字

感想

今回の実装で特に苦労した点は、タグ付与に関する制限の把握でした。

API 経由で付与できるタグには細かな制約がありますが、それらが体系的にまとまっている公式情報を見つけることができず、試行錯誤しながら仕様を確認する必要がありました。

運用上の気づきとして、Mailchimp はメールアドレスのエイリアス（例：+ 付きアドレス）と元のメールアドレスを同一のものとして認識します。
テスト用アカウントを複数登録した場合でも、Mailchimp 側では同一のメールアドレスとして扱われ、一定数を超えるとエラーが発生します。

そのため、Mailchimp 連携のテストを行う際には、テスト用メールアドレスの管理方法やテスト手順をあらかじめ検討する必要があると感じました。

お知らせ

技術ブログを週1〜2本更新中、ソーイをフォローして最新記事をチェック！
https://qiita.com/organizations/sewii

参考

• MailchimpAPI 公式ドキュメント(https://mailchimp.com/developer/)
• LaravelとMailChimp連携方法：ユーザーにメルマガ・ニュースレターを手軽に配信する(https://biz.addisteria.com/laravel_mailchimp/)