一覧が同じ100件を返し続ける。カーソルは2つ渡し、配信停止はdndSettingsで読む

顧客の一覧を、Claude Codeに全部取らせたい。件数を数えたい。配信を止めた人を洗い出したい。どれも、一覧APIを最後まで読むところから始まります。

私たちは、この一覧の読み方で3回つまずきました。ページの送り方、日時の型、そして配信停止の判定です。順に書きます。

一覧が、同じ100件を無限に返す

コンタクトの一覧は、1回に100件まで取れます。次のページへ進むには、前のページの最後の印を渡します。応答の末尾に、次に渡す印が付いて返ります。

そこで、その印のIDだけを次の呼び出しに渡して、ページを送りました。すると、応答は200で、印も毎回返ってきます。ところが、中身は同じ100件のままでした。

私たちは、これに気づかず41ページを回し、「4,100件取れた」と記録しました。実際は、100件を41回ぶん重複して受け取っていただけで、本当の総数は応答に付く総数の欄にある696件でした。

直し方は、カーソルを2つ渡すこと

次のページへ進むには、2つの印を一緒に渡します。

• 前のページ末尾のID
• 前のページ末尾の追加日時（ミリ秒の数値）

片方だけでは進みません。2つ揃えて、はじめて次のページが返ります。

あわせて、毎回の検証を入れます。受け取ったIDの集合から重複を取り除き、新しい件が0件になったら打ち切ります。最後に、応答の総数と集めた件数が一致するかを確かめます。一致するまでは、「全件取れた」と言わないことです。

会話の日時は、数値とISOで型が違う

次の罠は、日時です。会話の一覧に付く最終メッセージの日時は、エポックのミリ秒の数値で返ります。一方、その会話をたどって読み出すメールの追加日時は、ISO形式の文字列です。

同じ「日時」なのに、型が違います。ISO形式と決め打ちで読むと、会話の側が毎回例外になります。例外を握りつぶして「窓の外」と扱う作りだと、候補が黙って0件になります。テストは通るのに、本番のデータでは何も拾えない、という出方をします。

日時を読む関数は1つにまとめる

私たちは、数値とISOの両方を受けて、1つの形に揃える関数を作りました。日時を読む箇所は、すべてこの関数を通します。

会話の絞り込みにも注意が要ります。「最終メッセージが期間の中」で絞ると、期間より後にも動きがあった会話を、丸ごと落とします。その会話にある、期間内のメールも一緒に消えます。会話は「期間の開始以降に動きがある」で絞り、期間の判定は1通ごとの日時で行います。

ページ送りでは、前ページ末尾の最終メッセージの日時を渡します。ページ番号や読み飛ばしの指定を付けても、黙って1ページ目が返るだけです。

dndの欄は、配信を止めた人を映さない

3つ目は、配信を止めた人の判定です。コンタクトには、配信停止を意味しそうな dnd という欄があります。

私たちは、本体のアカウントの731件を全数読み出しました。実際に配信を止めている人は3人いましたが、3人とも dnd は false でした。dnd が true の人は、0件でした。個別に読み出すと、dnd の欄そのものが応答に無いこともわかりました。

判定はdndSettingsで行う

配信停止の判定に使えるのは、dndSettings の中のメールの状態です。ここが active なら、メールが止まっています。dndSettings が空でなくても、状態が inactive なら、止まっていません。手動で止めて、あとで解除した跡だからです。

タグで除外している場合は、別の系統です。dndSettings とタグの両方を見て、数え漏れを防ぎます。

購読管理の口は、4本とも404でした。新しい方式で止めた人は、APIからは見えません。「停止者ゼロ」と出ても、それは「測れていない」のかもしれません。

一斉メールで、届かなかった数を知る

もう一つ、見つけた口があります。一斉メールの予約の一覧は、予定の総数と成功の数を返します。この差が、無言で届かなかった数です。ある日の実測では、156件に対して成功が143件で、13件の差がありました。

画面では、失敗もエラーも0と表示されます。赤くならないので、一覧の数字を自分で引き算しないと気づけません。ただし、どの宛先に届かなかったかは、この口からはわかりません。

「0件」を、送信なしと読まない

一覧を読む関数には、返り値に2つの数を載せておきます。読めた会話の総数と、期間の先頭まで遡れたかどうかです。

遡れていないのに0件と出たなら、それは「送信がなかった」ではなく、「そこまで読めていない」という意味です。測れていないことを、無かったことと読み違えると、空のメール事故の調査のように、見るべき場所を外します。私たちは、遡れていない場合は、結果を「未確認」として返すようにしました。

次に読む

読むだけでなく、作ったものが動いたかを確かめる段階に進みます。ワークフローの読み取りと、疎通テストの組み方は、ワークフローの記事にまとめました。