---
title: "nextmail.signups"
description: "Every method in this namespace: its signature, its parameters, what it returns and an example."
url: "https://nextmail.sh/docs/sdk/reference/signups"
area: "TypeScript"
category: "Reference"
---

# nextmail.signups

Every method in this namespace: its signature, its parameters, what it returns and an example.

## Methods

An agent creates an account for a person with no credential at all: it starts a sign-up for their address, the person reads it the six-digit code emailed to them, and finishing the sign-up returns an API key for the new account.

### `signups.create()`

Start creating an account for a person

```ts
create(body: SignUpCreate, options?: RequestScope): Promise<SignUpResource>
```

Starts a sign-up for an address and emails it a six-digit code that works once and runs out after 10 minutes. It needs no credential. Ask the person for the code, then finish with `verify`, which creates the account and returns its API key.

An address that cannot receive mail, or one on a disposable domain, is 422 `sign_up_address_refused` and nothing is sent. When the address already has an account, no code is sent: that person is emailed how to connect an agent to the account they have, and this call resolves exactly as it would for a new address, so it never reveals who has an account.

One network may start 3 sign-ups an hour, counted together with sign-ups made in the apps, and one address 5 an hour. The next is 429 `sign_up_rate_limited` with `Retry-After`. When the email cannot be sent it is 503 `sign_up_undeliverable` and no sign-up is waiting.

**Parameters**

- `body.email` (`string`, required): The address the account signs in with. The code goes there, so it has to be one the person reads.
- `body.name` (`string`): The name of the person the account is for. The address stands in when it is left out.
- `body.agent` (`string`): Who is asking, such as `Claude Code`. The emails name it, and the key is named after it.
- `body.scopes` (`Array<ApiScope>`): What the key may do. Every scope when it is left out.
- `options.signal` (`AbortSignal`): Cancels the request.
- `options.apiKey` (`string`): Ignored and never sent. Starting a sign-up is anonymous.

**Returns**

`SignUpResource` with the `id` to finish with, `sentTo`, the masked address the code went to, and `expiresAt`.

**Example**

```ts
const signups = createSignups()

const signUp = await signups.create({ email: 'ada@example.com', name: 'Ada Lovelace', agent: 'Claude Code' })

console.log(`Ask for the code sent to ${signUp.sentTo}`)
```

**Notes**

- Call it on `createSignups()`, which needs no key. A client made with `createClient` or `new Nextmail` needs one, and an agent signing up has none yet.
- Not retried automatically, since a retry would email a second code under a new id.
- Every scope a key can hold is given unless `scopes` lists fewer, and the person can narrow the key later in Settings, API keys.

Also available in: API [`POST /signups`](https://nextmail.sh/docs/api/reference/sign-up#post-signups); Python [`signups.create()`](https://nextmail.sh/docs/python/reference/signups#create); Ruby [`signups.create`](https://nextmail.sh/docs/ruby/reference/signups#create); PHP [`signups->create`](https://nextmail.sh/docs/php/reference/signups#create); Go [`Signups.Create`](https://nextmail.sh/docs/go/reference/signups#create); Java [`signups().create`](https://nextmail.sh/docs/java/reference/signups#create); C# [`Signups.CreateAsync`](https://nextmail.sh/docs/csharp/reference/signups#create); CLI [`nextmail signups create`](https://nextmail.sh/docs/cli/reference/signups#signups-create).

### `signups.verify()`

Finish a sign-up with the code and get the key

```ts
verify(signUpId: string, code: string, options?: RequestScope): Promise<SignUpAccountResource>
```

Sends the six-digit code the person read from their email. A right code creates the account, its workspace and its free address, and issues an API key that acts for the new owner. It needs no credential and resolves with one: `apiKey.token` is shown here and nowhere else, so store it before anything else. The person gets a welcome email with a link to set a password, and sees the key under Settings, API keys.

A sign-up takes 5 codes. A wrong one is 400 `sign_up_code_invalid` with the tries left in the message, and the last wrong one cancels the sign-up with 429 `sign_up_locked`. A code that ran out, was used already or belongs to no sign-up is 400 `sign_up_code_expired`, and an address that got an account while the code was waiting is 409 `sign_up_address_taken`.

**Parameters**

- `signUpId` (`string`, required): The `id` `create` resolved with.
- `code` (`string`, required): The six digits from the email the person received.
- `options.signal` (`AbortSignal`): Cancels the request.
- `options.apiKey` (`string`): Ignored and never sent. Finishing a sign-up is anonymous.

**Returns**

`SignUpAccountResource` with `userId`, `email`, `name`, `workspaceId`, the free `address` or null, and `apiKey` with its `id`, `name`, `scopes` and one-time `token`.

**Example**

```ts
const signups = createSignups()

const account = await signups.verify(signUp.id, '123456')

const client = createClient({ apiKey: account.apiKey.token })

console.log(account.address, account.workspaceId)
```

**Notes**

- Call it on `createSignups()`, which needs no key, then build a client with the key it returns.
- Not retried automatically, since the code works once.
- The key starts with every scope unless the sign-up asked for fewer.

Also available in: API [`POST /signups/{id}/verify`](https://nextmail.sh/docs/api/reference/sign-up#post-signups-id-verify); Python [`signups.verify()`](https://nextmail.sh/docs/python/reference/signups#verify); Ruby [`signups.verify`](https://nextmail.sh/docs/ruby/reference/signups#verify); PHP [`signups->verify`](https://nextmail.sh/docs/php/reference/signups#verify); Go [`Signups.Verify`](https://nextmail.sh/docs/go/reference/signups#verify); Java [`signups().verify`](https://nextmail.sh/docs/java/reference/signups#verify); C# [`Signups.VerifyAsync`](https://nextmail.sh/docs/csharp/reference/signups#verify); CLI [`nextmail signups verify`](https://nextmail.sh/docs/cli/reference/signups#signups-verify).