> ## 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.

# 配信メッセージ更新

> **プレビュー機能。仕様は今後変更される可能性があります。** 配信メッセージを部分更新します。指定したフィールドのみ変更され、省略したフィールドは既存値を維持します。

- `channel` と `type` は変更できません（既存と異なる値を指定すると `422`）。
- 空のボディは何も変更しません（`200` で現在値を返します）。
- `conditions` / `url_actions` / `line.messages` は指定すると全件置換されます。
- `status` を `draft` → `reserved` にすると予約実行（配信予約作成）、`reserved` → `draft` にすると予約解除（配信予約削除）が行われます。
- `reserved` 状態のメッセージで送信日時・条件・A/Bテストを変更すると配信予約が自動で再作成されます。再作成から5分間は再変更できず、`429 cooldown_active`（`details.retry_after` に再試行可能になる日時（`Y-m-d H:i:s` 形式の文字列））が返ります。
- `sending` / `completed` のメッセージは更新できません（`409`）。


`PATCH`

```
https://api.utage-system.com/v1/accounts/{account_id}/scenarios/{scenario_id}/messages/{message_id}
```

<Note>この機能はプレビュー版です。仕様が変更される場合があります。</Note>


## OpenAPI

````yaml PATCH /accounts/{account_id}/scenarios/{scenario_id}/messages/{message_id}
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}/messages/{message_id}:
    patch:
      tags:
        - 配信メッセージ
      summary: 配信メッセージ更新
      description: >
        **プレビュー機能。仕様は今後変更される可能性があります。**
        配信メッセージを部分更新します。指定したフィールドのみ変更され、省略したフィールドは既存値を維持します。


        - `channel` と `type` は変更できません（既存と異なる値を指定すると `422`）。

        - 空のボディは何も変更しません（`200` で現在値を返します）。

        - `conditions` / `url_actions` / `line.messages` は指定すると全件置換されます。

        - `status` を `draft` → `reserved` にすると予約実行（配信予約作成）、`reserved` → `draft`
        にすると予約解除（配信予約削除）が行われます。

        - `reserved`
        状態のメッセージで送信日時・条件・A/Bテストを変更すると配信予約が自動で再作成されます。再作成から5分間は再変更できず、`429
        cooldown_active`（`details.retry_after` に再試行可能になる日時（`Y-m-d H:i:s`
        形式の文字列））が返ります。

        - `sending` / `completed` のメッセージは更新できません（`409`）。
      operationId: updateMessage
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: scenario_id
          in: path
          required: true
          description: シナリオID
          schema:
            type: string
        - name: message_id
          in: path
          required: true
          description: メッセージID
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageUpdateRequest'
      responses:
        '200':
          description: 更新された配信メッセージ
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/MessageDetail'
                  warnings:
                    type: array
                    description: >
                      `reserved`
                      状態でメールを変更した場合に、配信解除URL欠如・DKIM未設定などが検出されると返されることがあります。
                    items:
                      type: string
        '400':
          description: >
            SMS配信の前提条件を満たしていません。SMS未設定（`sms_not_configured`）、SMS送信クレジット不足（`sms_no_credit`）など。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: |
            メッセージの状態が更新を許可しません（`sending` / `completed` は更新不可）。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: conflict
                  message: 送信中または完了済みのメッセージは更新できません。
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          description: >
            配信予約作成直後のクールダウン中です（作成後5分間）。`details.retry_after` に再試行可能になる日時（`Y-m-d
            H:i:s` 形式の文字列）が含まれます。なお、このエンドポイントは共通のレート制限の対象でもあるため、リクエスト上限を超えた場合は
            `rate_limit_exceeded` も返り得ます。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: cooldown_active
                  message: キュー作成後5分間は再作成できません
                  details:
                    retry_after: '2026-06-19 12:39:56'
components:
  parameters:
    AccountId:
      name: account_id
      in: path
      required: true
      description: アカウントID
      schema:
        type: string
  schemas:
    MessageUpdateRequest:
      type: object
      description: |
        配信メッセージ更新リクエスト（部分更新）。指定したフィールドのみ変更され、省略した
        フィールドは既存値を維持します。`channel` / `type` は変更できません（異なる値を指定すると
        `422`）。`conditions` / `url_actions` / `line.messages` は指定すると全件置換されます。
      properties:
        status:
          type: string
          enum:
            - draft
            - reserved
          description: >
            ステータス。`draft`→`reserved` で予約実行（配信予約作成）、`reserved`→`draft`
            で予約解除（配信予約削除）。
        title:
          type: string
          maxLength: 255
          nullable: true
          description: 管理名称
        use_ab_test:
          type: boolean
          nullable: true
          description: A/Bテスト使用
        send_type:
          type: string
          description: 送信タイプ（message_create と同じ）
        send_date:
          type: string
          format: date
          description: 送信日（broadcast用、YYYY-MM-DD）
        send_day:
          type: integer
          description: 送信日数（step / reminder 用）
        send_hour:
          type: integer
          minimum: 0
          maximum: 23
          description: 送信時（0-23）
        send_min:
          type: integer
          minimum: 0
          maximum: 59
          description: 送信分（0-59）
        send_timing:
          type: string
          enum:
            - before
            - after
            - today
            - addition_before
            - addition_after
          description: 送信タイミング（reminder用）
        base_date:
          type: string
          description: 基準日の読者項目名（reminder用）
        step_send_type:
          type: string
          enum:
            - none
            - immediately
          description: ステップ送信タイプ（step用）
        mail:
          type: object
          description: メール原稿（省略時は既存維持）。type は変更不可のため指定不要。
        line:
          allOf:
            - $ref: '#/components/schemas/LineContent'
          description: LINE原稿（省略時は既存維持）。messages 指定時は全件置換。sender_id のみの指定も可。
        sms:
          allOf:
            - $ref: '#/components/schemas/SmsContent'
          description: SMS原稿（省略時は既存維持）
        action_id:
          type: string
          nullable: true
          description: 配信後に実行するアクションID。null で解除。
        shorten_type:
          type: string
          enum:
            - shorten_url
            - original_url
          description: URL置換方法
        shorten_domain:
          type: string
          nullable: true
          description: URL置換ドメイン。null で解除。
        conditions:
          type: array
          description: 配信条件（指定時は全件置換、空配列で条件解除）
          items:
            type: object
        url_actions:
          type: array
          description: URLアクション（指定時は全件置換、空配列でクリア）
          items:
            type: object
    MessageDetail:
      type: object
      description: >
        配信メッセージの詳細。共通フィールドに加え、`type` に応じた送信タイミング系フィールド

        （`send_type` / `send_date` / `send_day` / `send_hour` / `send_min` /
        `base_date` /

        `send_timing` / `step_send_type` 等）と、`channel` に応じた原稿（`mail` / `line` /
        `sms`）、

        `url_actions` を含みます。
      properties:
        id:
          type: string
          description: メッセージID
        channel:
          type: string
          enum:
            - mail
            - line
            - sms
            - action
          description: 媒体
        type:
          type: string
          enum:
            - broadcast
            - step
            - reminder
          description: 配信タイプ
        status:
          type: string
          enum:
            - draft
            - reserved
            - sending
            - completed
          description: ステータス
        title:
          type: string
          nullable: true
          description: 管理名称
        mail:
          type: object
          nullable: true
          description: メール原稿全体（channel=mail のとき）
        line:
          type: object
          nullable: true
          description: LINE原稿（channel=line のとき）。{sender_id, messages[]}
          properties:
            sender_id:
              type: string
              nullable: true
              description: 送信者ID
            messages:
              type: array
              description: LINEメッセージの配列
              items:
                type: object
        sms:
          type: object
          nullable: true
          description: SMS原稿（channel=sms のとき）
        url_actions:
          type: array
          description: URLアクションの配列
          items:
            type: object
      additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: エラーコード
            message:
              type: string
              description: エラーメッセージ
            details:
              type: object
              nullable: true
              description: エラーの補足情報（retry_afterやフィールド別エラー等）。エラー種別により含まれる場合があります。
    LineContent:
      type: object
      description: LINE原稿（channel=line のとき指定）。タイプ別の詳細は LINEメッセージタイプ定義を参照。
      properties:
        sender_id:
          type: string
          description: 送信者ID
        messages:
          type: array
          minItems: 1
          maxItems: 5
          description: LINEメッセージの配列（1〜5件）
          items:
            type: object
    SmsContent:
      type: object
      description: SMS原稿（channel=sms のとき指定）
      properties:
        message:
          type: string
          maxLength: 360
          description: 本文（最大360文字、絵文字不可）
  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トークンとして指定

````