Clients should submit a POST request

api/client-server/administrative_contact.yaml

@@ -145,10 +145,10 @@ paths:
                   description: |-
                     An optional field containing a URL where the client must
                     submit the validation token to, with identical parameters
-                    to the Identity Service API's
+                    to the Identity Service API's ``POST
-                    ``/validate/email/submitToken`` endpoint. The homeserver
+                    /validate/email/submitToken`` endpoint. The homeserver must
-                    must send this token to the user (if applicable), which
+                    send this token to the user (if applicable), which should
-                    should then be prompted to provide it to the client.
+                    then be prompted to provide it to the client.
 
                     If this field is not present, the client can assume that
                     verification will happen without the client's involvement.

api/client-server/definitions/request_token_response.yaml

@@ -24,15 +24,13 @@ properties:
   submit_url:
     type: string
     description: |-
-      An optional field containing a URL where the client must
+      An optional field containing a URL where the client must submit the
-      submit the validation token to, with identical parameters
+      validation token to, with identical parameters to the Identity Service
-      to the Identity Service API's
+      API's ``POST /validate/email/submitToken`` endpoint. The homeserver must
-      ``/validate/email/submitToken`` endpoint. The homeserver
+      send this token to the user (if applicable), which should then be
-      must send this token to the user (if applicable), which
+      prompted to provide it to the client.
-      should then be prompted to provide it to the client.
 
-      If this field is not present, the client can assume that
+      If this field is not present, the client can assume that verification
-      verification will happen without the client's
+      will happen without the client's involvement.
-      involvement.
     example: "https://example.org/path/to/submitToken"
 required: ['sid']