> ## Documentation Index > Fetch the complete documentation index at: https://docs.utage-system.com/llms.txt > Use this file to discover all available pages before exploring further. # 読者作成 > **プレビュー機能。仕様は今後変更される可能性があります。** 指定シナリオに読者を1件登録します。オプトインを取得済みのアドレスのみ登録してください。 読者項目は `scenario_fields`（シナリオ固有。メールアドレスは `scenario_fields.mail` に指定）と `common_fields`（全シナリオ共通）の2グループで指定します。 メール／メール・LINE併用アカウントでは `mail` が必須です。各グループのキーは項目名（置き換え文字名）で、置き換え文字一覧の `field_group` で各項目がどちらのグループかを確認できます。 このエンドポイントはバーストが発生するため分間レート制限（60回/分）の対象外で、独自の時間/月間上限で制御されます。 `POST` ``` https://api.utage-system.com/v1/accounts/{account_id}/scenarios/{scenario_id}/readers ``` この機能はプレビュー版です。仕様が変更される場合があります。 ## OpenAPI ````yaml POST /accounts/{account_id}/scenarios/{scenario_id}/readers openapi: 3.0.3 info: title: UTAGE API description: | UTAGEのパブリックAPIです。ファネル、配信アカウント、シナリオ、メディアなどのリソースをプログラムから操作できます。 ## 認証 すべてのリクエストにAPIキーによるBearer認証が必要です（要素タイプエンドポイントを除く）。 ``` Authorization: Bearer {api_key} ``` APIキーはUTAGE管理画面から発行できます。 ## レート制限 リクエスト数には以下の制限があります。 | 分間上限 | 日間上限 | |----------|----------| | 60リクエスト/分 | 10,000リクエスト/日 | レスポンスヘッダーで現在の使用状況を確認できます。 | ヘッダー | 説明 | |----------|------| | X-RateLimit-Limit | 分間の上限値 | | X-RateLimit-Remaining | 分間の残りリクエスト数 | | X-RateLimit-Reset | 制限がリセットされるUNIXタイムスタンプ | 上限を超えた場合は `429 Too Many Requests` が返されます。 ## エラーレスポンス エラー時は以下の形式で返されます。 ```json { "error": { "code": "error_code", "message": "エラーメッセージ" } } ``` version: '1.0' contact: name: UTAGE サポート servers: - url: https://api.utage-system.com/v1 description: UTAGE API security: - BearerAuth: [] tags: - name: ファネル description: ファネルの作成・更新・一覧取得 - name: ステップ description: ファネル内のステップの作成・更新・並び替え - name: ページ description: ステップ内のページの作成・更新・取得・削除 - name: 配信アカウント description: 配信アカウントの作成・一覧取得 - name: シナリオ description: シナリオの作成・一覧取得 - name: メディア description: 動画・音声・通常メディアの一覧取得とアップロード - name: 要素タイプ description: ファネルページ・HTMLメールの要素タイプ定義、LINEメッセージタイプ・配信条件タイプの取得（認証不要） - name: ファネル統計 description: ファネルの集計データ・登録者・登録経路の取得（プレビュー） - name: 配信メッセージ description: 配信メッセージの作成・更新・テスト送信・配信統計、置き換え文字の取得（プレビュー） - name: 読者 description: 読者の作成・更新・取得、ラベル・配信履歴・開封/クリック履歴の取得（プレビュー） - name: LINE description: LINE友だち・カスタム送信者・1対1チャット・テンプレートの操作（プレビュー） - name: ラベル・共通読者・登録経路 description: ラベル・共通読者・アクション・登録経路の操作（プレビュー） paths: /accounts/{account_id}/scenarios/{scenario_id}/readers: post: tags: - 読者 summary: 読者作成 description: > **プレビュー機能。仕様は今後変更される可能性があります。** 指定シナリオに読者を1件登録します。オプトインを取得済みのアドレスのみ登録してください。 読者項目は `scenario_fields`（シナリオ固有。メールアドレスは `scenario_fields.mail` に指定）と `common_fields`（全シナリオ共通）の2グループで指定します。 メール／メール・LINE併用アカウントでは `mail` が必須です。各グループのキーは項目名（置き換え文字名）で、置き換え文字一覧の `field_group` で各項目がどちらのグループかを確認できます。 このエンドポイントはバーストが発生するため分間レート制限（60回/分）の対象外で、独自の時間/月間上限で制御されます。 operationId: createReader parameters: - $ref: '#/components/parameters/AccountId' - name: scenario_id in: path required: true description: シナリオID schema: type: string requestBody: required: true content: application/json: schema: type: object required: - opt_in_confirmed properties: opt_in_confirmed: type: boolean description: オプトイン取得済みの確認（`true` のみ受付・必須）。オプトインを取得済みのアドレスのみ登録すること scenario_fields: type: object description: > シナリオ固有の読者項目（キー=項目名、値=文字列）。メールアドレスはここに指定（`scenario_fields.mail`）。 `mail` はメール/メール・LINE併用アカウントでは必須で、RFC・DNS検証あり（最大255文字）。 common_fields: type: object description: 全シナリオ共通の読者項目（キー=項目名、値=文字列） has_step_immediately: type: boolean description: 登録直後のステップ配信の対象にする（デフォルトfalse。作成時のみ指定可能） has_step_scheduled: type: boolean description: ステップ配信の対象にする（デフォルトfalse） has_reminder: type: boolean description: リマインダ配信の対象にする（デフォルトfalse） allow_duplicates: type: boolean description: >- 重複登録を許可する（デフォルトfalse）。falseのとき、同一シナリオ内に配信解除されていない同一メールアドレスの読者が既に存在すると422になります responses: '201': description: 作成された読者 content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Reader' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationError' '429': description: > 読者作成のリソース上限を超過しました。分間レート制限とは別枠で、時間/月間/累計の上限に応じて以下のコードを返します。 - `hourly_limit_exceeded`: 1時間の作成上限に達した - `monthly_limit_exceeded`: 月間の作成上限に達した（`details.retry_after` に再試行可能になる日時（`Y-m-d H:i:s` 形式の文字列）を含む） - `total_limit_exceeded`: 累計の作成上限に達した content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: monthly_limit_exceeded message: 月間の作成上限に達しました details: resource_type: reader retry_after: '2026-06-20 00:00:00' components: parameters: AccountId: name: account_id in: path required: true description: アカウントID schema: type: string schemas: Reader: type: object description: > 読者の詳細情報。読者項目はトップレベルではなく `scenario_fields`（シナリオ固有）/ `common_fields`（全シナリオ共通）の2グループで返る。トップレベルはシステム情報のみ。 properties: id: type: string description: 読者ID common_reader_id: type: string nullable: true description: 共通読者ID（同一人物を全シナリオで識別するID） scenario_id: type: string description: シナリオID ip: type: string nullable: true description: 登録時のIPアドレス line_display_name: type: string nullable: true description: LINE登録名 line_picture_url: type: string nullable: true description: LINEプロフィール画像URL line_friend_id: type: string nullable: true description: LINE友だちID base_date: type: string nullable: true description: 配信基準日時 is_blocked: type: boolean description: 配信停止状態 is_line_blocked: type: boolean description: LINEブロック状態 is_mail_error: type: boolean description: 配信エラー状態 is_sms_blocked: type: boolean description: SMS配信停止状態 block_datetime: type: string nullable: true description: 配信停止日時 partner: type: object nullable: true description: 紹介パートナー情報（存在しない場合はnull） properties: project_name: type: string name: type: string reward: type: integer has_step_scheduled: type: boolean description: ステップ配信の対象か has_reminder: type: boolean description: リマインダ配信の対象か message_tracking_id: type: string nullable: true description: シナリオ登録経路ID message_tracking_name: type: string nullable: true description: シナリオ登録経路名 funnel_tracking_id: type: string nullable: true description: ファネル登録経路ID funnel_tracking_name: type: string nullable: true description: ファネル登録経路名 referrer: type: string nullable: true description: リファラー labels: type: array description: 付与されているラベル items: $ref: '#/components/schemas/ReaderLabel' scenario_fields: type: object description: シナリオ固有の読者項目（キー=置き換え文字名。未設定は空オブジェクト） common_fields: type: object description: 全シナリオ共通の読者項目（キー=置き換え文字名。未設定は空オブジェクト） memo: type: string nullable: true description: メモ created_at: type: string description: 登録日時 ErrorResponse: type: object properties: error: type: object properties: code: type: string description: エラーコード message: type: string description: エラーメッセージ details: type: object nullable: true description: エラーの補足情報（retry_afterやフィールド別エラー等）。エラー種別により含まれる場合があります。 ReaderLabel: type: object description: ラベル properties: id: type: string description: ラベルID name: type: string description: ラベル名 assigned_at: type: string nullable: true description: ラベル付与日時 responses: Unauthorized: description: 認証エラー。APIキーが無効または未指定。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: unauthorized message: 認証に失敗しました NotFound: description: 指定されたリソースが見つかりません。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: not_found message: リソースが見つかりません ValidationError: description: バリデーションエラー。リクエストパラメータが不正。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: validation_error message: バリデーションエラーが発生しました securitySchemes: BearerAuth: type: http scheme: bearer description: APIキーをBearerトークンとして指定 ````