# Block disposable emails and fake sign-ups (/docs/guides/block-disposable-emails)

Fake accounts start with an address nobody reads: a disposable inbox, a domain that can't receive
mail, or the same mailbox with a new `+tag`. coss.com Risk checks the address, the IP and the browser
at sign-up and answers `allow`, `review` or `block`, with the reasons behind it.

## Check an email address [#check-an-email-address]

`coss.risk.checkEmail()` returns the facts about one address. It's stateless: nothing is stored or
counted, so it suits checking a field as someone fills in the form.

```ts twoslash
import { Coss } from "coss";
const coss = new Coss();
// ---cut---
const { data: check } = await coss.risk.checkEmail("ada@gnail.com");

if (check?.disposable) console.log("Use a permanent email address.");
if (check?.deliverability === "undeliverable") console.log("This domain can't receive email.");
if (check?.suggestion) console.log(`Did you mean ${check.suggestion}?`); // "gmail.com"
```

`deliverability` comes from DNS (MX, A and AAAA records): `undeliverable` when the domain doesn't
exist, has a null MX or has nothing to deliver to. `canonical` folds dots and `+tags` at Gmail and
similar providers, so two spellings of one inbox compare equal. It also reports `valid`,
`role_account` (`info@`), `free_provider` and [more](/docs/risk/lookups).

## Assess the sign-up [#assess-the-sign-up]

A check gives facts; an assessment gives a decision. `coss.risk.assess()` combines the email
signals with the IP address (Tor, cloud and hosting networks, VPNs), the browser, what the
environment has seen before (the same IP, subnet, domain or mailbox signing up again) and your own
lists and rules. This Next.js server action refuses `block`, asks `review` sign-ups to verify their
email first, and fails open if coss.com can't be reached:

```ts twoslash
"use server";
import { headers } from "next/headers";
import { Coss } from "coss";

const coss = new Coss();

export async function signUp(_prev: { error?: string } | null, formData: FormData) {
  const email = String(formData.get("email") ?? "");
  const device = formData.get("device");
  const requestHeaders = await headers();

  const { data: assessment, error } = await coss.risk.assess({
    event: "signup",
    user: { email },
    ip: requestHeaders.get("x-forwarded-for")?.split(",")[0]?.trim(),
    user_agent: requestHeaders.get("user-agent") ?? undefined,
    device: typeof device === "string" ? { token: device } : undefined,
  });
  if (error) console.error(error);

  if (assessment?.decision === "block") return { error: "We couldn't create your account." };

  await createUser(email, { verified: assessment?.decision === "allow" });
  return {};
}
// ---cut-after---
declare function createUser(email: string, options: { verified: boolean }): Promise<{ id: string }>;
```

Pass the client's address, not your proxy's (an `ip.private` reason means you sent the proxy's).
The first `x-forwarded-for` entry is right only when your hosting platform sets the header itself;
behind your own proxies, take the entry they appended. Don't show reasons to the person signing up,
apart from a typo suggestion (`email.typo`): they tell an attacker what to change.

The device token comes from `coss/device` in the browser, made when the form is submitted:

```tsx twoslash
"use client";
import { useActionState } from "react";
import { collectDevice } from "coss/device";
declare function signUp(prev: { error?: string } | null, formData: FormData): Promise<{ error?: string }>;
// ---cut---
export function SignUpForm() {
  const [state, action] = useActionState(signUp, null);
  return (
    <form action={(formData) => { formData.set("device", collectDevice()); action(formData); }}>
      <input name="email" type="email" required />
      <button type="submit">Sign up</button>
      {state?.error && <p>{state.error}</p>}
    </form>
  );
}
```

## Decisions and reasons [#decisions-and-reasons]

Each reason adds to a score, and the score decides with your thresholds. On its own, a disposable
address (`email.disposable`, weight 0.7) is `review` with the default thresholds; a disposable
address over Tor is `block`. The reasons that matter most for sign-ups:

| Reason | When |
| --- | --- |
| `email.disposable`, `email.undeliverable` | A disposable-mail domain, or one that can't receive mail. |
| `email.typo`, `email.role_account`, `email.domain_new` | A likely typo, a role account, a recently registered domain. |
| `duplicate.canonical_mailbox` | The mailbox already has an account (dots and `+tags` folded). |
| `velocity.signups_per_ip_1h`, `velocity.signups_per_mailbox_24h` | Many sign-ups from one IP address, or for one mailbox. |
| `ip.tor`, `ip.hosting_provider`, `device.automation` | Tor, a data center, an automated browser. |

`review` is for sign-ups you let through with limits: no free credits, email verification first,
or a look in the dashboard's review queue. Duplicate detection compares sign-ups that carry a user
id, so pass `user: { id }` once you have one. [Reasons and scores](/docs/risk/reasons) lists them all.

## Always block disposable addresses [#always-block-disposable-addresses]

To refuse every disposable address regardless of score, add a [rule](/docs/risk/rules). Rules run
before the thresholds, and the first match decides:

```ts twoslash
import { Coss } from "coss";
const coss = new Coss();
// ---cut---
await coss.risk.rules.create({
  name: "Disposable email",
  events: ["signup"],
  conditions: [{ field: "email.disposable", operator: "is", value: true }],
  action: "block",
});
// A domain the disposable list doesn't know yet:
await coss.risk.lists.add("block", { domain: "burner.example", note: "Seen in abuse" });
```

## Rate limit sign-ups per IP address [#rate-limit-sign-ups-per-ip-address]

Assessments already count sign-ups per IP address, subnet, email domain, mailbox and browser. For a
hard cap of your own, define a bucket and check it before assessing:

```ts twoslash
import { Coss } from "coss";
const coss = new Coss();
declare const ip: string;
// ---cut---
// Once, or in the dashboard (Risk → Rate limits):
await coss.risk.limitBuckets.create({ name: "signup.ip", limit: 10, period_seconds: 3600 });
// On every sign-up:
const { data: limit } = await coss.risk.limit({ bucket: "signup.ip", key: ip });
if (limit && !limit.allowed) throw new Error("Too many sign-ups. Try again later.");
```

## Test it [#test-it]

Sandbox keys (`coss_test_…`) know [test inputs](/docs/risk/testing): `ada@disposable.test` is
disposable, `ada@undeliverable.test` can't receive mail, and IP `192.0.2.1` is a Tor exit node.

## Next steps [#next-steps]

- [Risk assessments](/docs/risk): every signal, retries and failures.
- [Email, IP and phone checks](/docs/risk/lookups): the lookups on their own.
- [Devices](/docs/risk/devices): recognize one browser behind many accounts.
- [Lists, feedback and reviews](/docs/risk/lists-and-feedback): teach Risk about your users.
- [Better Auth](/docs/integrations/better-auth): assess before calling its sign-up, and send its
  verification emails through coss.com.
