フリップブックのメール許可リストを管理する

できること

フリップブックがメールでゲートされている場合、その許可リストに載っているアドレスだけが開けます。APIでは、ダッシュボードに一切触れることなく、このリストを次の4つの方法で管理できます。

• 現在のリストを取得する。自分で管理し続ける必要がなくなります。
• 1つ以上のアドレスを追加する（すでにあるものはそのまま）。
• 特定のアドレスを削除する。
• リスト全体を1回の呼び出しで置き換える。

このガイドでは、それぞれの方法、リクエストの正確な形、返ってくるレスポンス、そして多くの人がつまずく唯一の落とし穴（追加と置き換えの違い）を順を追って説明します。

始める前に

必要なものは次のとおりです。

• APIキー — すべてのリクエストでX-Api-Keyヘッダーとして送ります。（キーはアカウントのAPIページにあります。）
• メールでゲートされたフリップブックの**flipbookId**。許可リストは、メールゲート付きフリップブックのビューアーアクセスを制御します。
• すべてのリクエストの送信先はベースURL https://go.fliplink.meです。

書き込みリクエストのEmailsAllowedフィールドはform-urlencoded（JSONではありません）で、セミコロン区切り（alice@corp.com;bob@corp.com）です。カンマも受け付けられ、自動でセミコロンに変換されます。

4つのエンドポイントの一覧

現在のリストを取得する

必ずここから始めてください。変更する前にリストを取得し、正確な状態を把握しておきます。

curl -X GET 'https://go.fliplink.me/api/get-email-allow-list/96464' \
  -H 'X-Api-Key: YOUR_API_KEY'

レスポンス:

{ "Result": "OK", "EmailsAllowed": ["alice@corp.com", "bob@corp.com"], "Count": 2 }

EmailsAllowedは、きれいなJSON配列（セミコロン区切りの文字列ではありません）として返り、Countはその件数です。

残りを消さずにアドレスを追加する

すでにリストにいる全員を残したまま新しい人にアクセスを付与するには、追加を使います。これは追加的な操作で、誰も削除しません。

curl -X POST 'https://go.fliplink.me/api/add-email-allow-list/96464' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'EmailsAllowed=carol@corp.com;dan@corp.com'

レスポンス（更新後の完全なリスト）:

{ "Result": "OK", "EmailsAllowed": ["alice@corp.com", "bob@corp.com", "carol@corp.com", "dan@corp.com"], "Count": 4 }

特定のアドレスを削除する

指定した人のアクセスを取り消すには、削除を使います。指定したアドレスだけが削除され、それ以外は残ります。

curl -X DELETE 'https://go.fliplink.me/api/delete-email-allow-list/96464' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'EmailsAllowed=carol@corp.com'

レスポンス:

{ "Result": "OK", "EmailsAllowed": ["alice@corp.com", "bob@corp.com", "dan@corp.com"], "Count": 3 }

リスト全体を置き換える ⚠️

置き換えは、送ったアドレスだけで許可リスト全体を上書きします。ここが落とし穴です。1つのアドレスを送ると、それ以外の全員が消えます。

# これは1人を追加するのではなく、リストをこの1人だけにします。
curl -X PUT 'https://go.fliplink.me/api/set-email-allow-list/96464' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'EmailsAllowed=alice@corp.com'

この呼び出しの後は、alice@corp.comが唯一そのフリップブックを閲覧できるアドレスになります。置き換えは、完全なリストをゼロから定義したいとき（たとえば新しいフリップブックの初期設定など）だけに使ってください。日常的な「この人を追加／あの人を取り消し」といった変更には、代わりに追加と削除を使います。

リストを完全に空にするには、空の値を送ります。

curl -X PUT 'https://go.fliplink.me/api/set-email-allow-list/96464' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  --data-urlencode 'EmailsAllowed='

起こりうるエラー

• APIキーが欠けているか無効な場合 → HTTP 401。これはプレーンなUnauthorized HTMLページを返し、JSONボディはありません。X-Api-Keyヘッダーが存在し、正しいことを確認してください。
• 不明なflipbookId（またはキーが所有していないもの） → HTTP 200で{ "Result": "ERROR", "Message": "Item not found" }。

目安として、Result: "OK"は変更が適用されたこと、Result: "ERROR"は適用されなかったことを意味します。理由はMessageを読んでください。

推奨パターン

安全で予測可能な変更のために、次の手順をおすすめします。

1. 現在のリストをGETする。
2. 誰を追加・削除するか決める。
3. 細かい変更には追加／削除を使う（リストの残りには一切触れません）。
4. 置き換えは、リスト全体を一度に置き換えたいときだけにする。
5. もう一度GETして、最終状態を確認する。

この「取得 → 変更 → 再取得」のループにより、自分のシステムでリストを管理する必要がなくなり、追加のつもりで置き換えを使ってうっかりアクセスを消してしまうこともなくなります。