---
title: "Checks the address a visitor is about to sign up with, through the pipeline registration runs."
method: POST
path: "/api/auth/signup-preview"
tags: ["auth"]
---

# Checks the address a visitor is about to sign up with, through the pipeline registration runs.

`POST /api/auth/signup-preview`

## Request

- Base URL: `https://api.pricklymails.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.pricklymails.com/api/auth/signup-preview`
- Auth: none declared

## Request body

- SignupPreviewRequest: Request body for `POST /api/auth/signup-preview`.
  - `email` string, required: The address the visitor is about to sign up with.

## Response `200`

Which checks passed, and whether the address may sign up.

- SignupPreviewResponse: Response body for `POST /api/auth/signup-preview`.
  - `checks` PreviewChecksDto: Which checks passed for an address a visitor previews before signing up: the shape of the per-check result object, without the mail exchanger hostnames.
    - `catchall` union, required: A boolean provider or risk-flag check result (`disposable`, `role`, `free`, `catchall`).
      - boolean: The check ran; carries the real boolean result.
      - object: The check was not run.
        - `status` string, required: Always `"skipped"`.
    - `disposable` union, required: A boolean provider or risk-flag check result (`disposable`, `role`, `free`, `catchall`).
      - boolean: The check ran; carries the real boolean result.
      - object: The check was not run.
        - `status` string, required: Always `"skipped"`.
    - `free` union, required: A boolean provider or risk-flag check result (`disposable`, `role`, `free`, `catchall`).
      - boolean: The check ran; carries the real boolean result.
      - object: The check was not run.
        - `status` string, required: Always `"skipped"`.
    - `mx` union, required: The MX check of a signup preview.
      - object: The check ran.
        - `valid` boolean, required: Whether the domain publishes at least one usable mail exchanger.
      - object: The check was not run.
        - `status` string, required: Always `"skipped"`.
    - `role` union, required: A boolean provider or risk-flag check result (`disposable`, `role`, `free`, `catchall`).
      - boolean: The check ran; carries the real boolean result.
      - object: The check was not run.
        - `status` string, required: Always `"skipped"`.
    - `smtp` SmtpCheckDto, required: SMTP deliverability probe result.
      - `status` 'deliverable' | 'undeliverable' | 'unknown' | 'skipped', required: Outcome of the SMTP probe.
    - `syntax` boolean, required: Whether the email syntax is valid.
    - `typo` TypoCheckDto, required: Typo detection result.
      - `detected` boolean, required: Whether a domain typo was detected.
      - `suggested_domain` string, nullable: Corrected domain only (e.g. `"gmail.com"`), present on `GET /api/verify/{uuid}` when a typo was detected.
      - `suggestion` string, nullable: Full corrected address (e.g. `"user@gmail.com"`), only ever present on the synchronous submit response where the raw email is available in-request.
  - `preview_token` string, nullable: The handle on the stored result, to send back with `POST /api/auth/register` and `POST /api/auth/confirm`.
  - `signup` 'allowed' | 'undeliverable' | 'disposable' | 'unchecked', required: Whether the previewed address may sign up.

## Other responses

- `400`: Malformed email address (`signup_preview.invalid_email`).
- `429`: Too many previews and registrations from this address.

---

[API](https://skmtc.dev/pricklymails/apis/pricklymails-api.md) · [All operations](https://skmtc.dev/pricklymails/apis/pricklymails-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pricklymails/apis/pricklymails-api/revisions/b4225a92d8fb?raw)