Send a verification code to an address

POST /v1/signups

Starts the signup that ends in an account key, with no key and no login. Sends a 6 digit code to the address, valid for 10 minutes and 5 attempts, and answers 202 with the verify call. Sends are capped at 3 per address per hour, 10 per IP per hour, and 25 per client fingerprint per day; past a cap the response is 429 signup_send_limited with retry_after_seconds and an unlock whose action is this call. An address that already has an account gets a code too; verifying it mints a key on that account. Send { "email": "agent@example.com" }, with an optional "src" naming the surface that sent you.

Request body

{
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "maxLength": 254,
            "description": "The address the verification code is sent to. Case is folded; the same address in any casing is one account and one send budget."
          },
          "src": {
            "type": "string",
            "maxLength": 32,
            "description": "The agent surface that sent you, as a value from the ?src= registry. Also accepted as ?src= on the URL. The unlock in a refusal carries it back."
          }
        },
        "required": [
          "email"
        ]
      }
    }
  }
}

Responses

{
  "description": "Code sent",
  "headers": {
    "X-Request-Id": {
      "$ref": "#/components/headers/X-Request-Id"
    },
    "X-Arcmira-Version": {
      "$ref": "#/components/headers/X-Arcmira-Version"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/SignupSentResponse"
      }
    }
  }
}

{
  "$ref": "#/components/responses/InvalidRequest"
}

{
  "$ref": "#/components/responses/NotFound"
}

{
  "description": "Rate limit exceeded. Retry-After carries the wait.",
  "headers": {
    "X-Request-Id": {
      "$ref": "#/components/headers/X-Request-Id"
    },
    "X-Arcmira-Version": {
      "$ref": "#/components/headers/X-Arcmira-Version"
    },
    "Retry-After": {
      "$ref": "#/components/headers/Retry-After"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}

{
  "$ref": "#/components/responses/ServerError"
}

{
  "description": "server_error. The verification email could not be sent. Retry-After carries the wait.",
  "headers": {
    "X-Request-Id": {
      "$ref": "#/components/headers/X-Request-Id"
    },
    "X-Arcmira-Version": {
      "$ref": "#/components/headers/X-Arcmira-Version"
    },
    "Retry-After": {
      "$ref": "#/components/headers/Retry-After"
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Error"
      }
    }
  }
}

Operation definition

{
  "tags": [
    "Meta"
  ],
  "operationId": "create_signup",
  "summary": "Send a verification code to an address",
  "description": "Starts the signup that ends in an account key, with no key and no login. Sends a 6 digit code to the address, valid for 10 minutes and 5 attempts, and answers 202 with the verify call. Sends are capped at 3 per address per hour, 10 per IP per hour, and 25 per client fingerprint per day; past a cap the response is 429 signup_send_limited with retry_after_seconds and an unlock whose action is this call. An address that already has an account gets a code too; verifying it mints a key on that account. Send { \"email\": \"agent@example.com\" }, with an optional \"src\" naming the surface that sent you.",
  "security": [],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "email": {
              "type": "string",
              "maxLength": 254,
              "description": "The address the verification code is sent to. Case is folded; the same address in any casing is one account and one send budget."
            },
            "src": {
              "type": "string",
              "maxLength": 32,
              "description": "The agent surface that sent you, as a value from the ?src= registry. Also accepted as ?src= on the URL. The unlock in a refusal carries it back."
            }
          },
          "required": [
            "email"
          ]
        }
      }
    }
  },
  "responses": {
    "202": {
      "description": "Code sent",
      "headers": {
        "X-Request-Id": {
          "$ref": "#/components/headers/X-Request-Id"
        },
        "X-Arcmira-Version": {
          "$ref": "#/components/headers/X-Arcmira-Version"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SignupSentResponse"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/InvalidRequest"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    },
    "429": {
      "description": "Rate limit exceeded. Retry-After carries the wait.",
      "headers": {
        "X-Request-Id": {
          "$ref": "#/components/headers/X-Request-Id"
        },
        "X-Arcmira-Version": {
          "$ref": "#/components/headers/X-Arcmira-Version"
        },
        "Retry-After": {
          "$ref": "#/components/headers/Retry-After"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "500": {
      "$ref": "#/components/responses/ServerError"
    },
    "503": {
      "description": "server_error. The verification email could not be sent. Retry-After carries the wait.",
      "headers": {
        "X-Request-Id": {
          "$ref": "#/components/headers/X-Request-Id"
        },
        "X-Arcmira-Version": {
          "$ref": "#/components/headers/X-Arcmira-Version"
        },
        "Retry-After": {
          "$ref": "#/components/headers/Retry-After"
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}