---
title: "nextmail.signups"
description: "Every method in this namespace: its signature, its parameters, what it returns and an example."
url: "https://nextmail.sh/docs/python/reference/signups"
area: "Python"
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. `create_signups()` builds this namespace without a key, and `create_async_signups()` builds its async twin. A `Nextmail` client needs a key, which an agent signing up does not have yet, though the calls work on one too and never send its key.

### `signups.create()`

Start creating an account for a person

```python
def create(
    body: SignUpCreate,
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> 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 sends no credential, even from a client that holds one. 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 returns 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.

Sends no credential.

**Parameters**

- `body['email']` (`str`, required): The address the account signs in with. The code goes there, so it has to be one the person reads.
- `body['name']` (`str`): The name of the person the account is for. The address stands in when it is left out.
- `body['agent']` (`str`): Who is asking, such as `Claude Code`. The emails name it, and the key is named after it.
- `body['scopes']` (`list[ApiScope]`): What the key may do, as members of `API_SCOPES`. Every scope when it is left out.
- `api_key` (`str`): Ignored and never sent. Starting a sign-up needs no credential.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `NextmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`SignUpResource`, a dict with `object` set to `sign_up`, the `id` to finish with, `sentTo`, the masked address the code went to, and `expiresAt`.

**Example**

```python
from nextmail import nextmail

signups = create_signups()

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

print(f'Ask for the code sent to {sign_up["sentTo"]}')
```

**Notes**

- Call it on `create_signups()`, which needs no key. A `Nextmail` client 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.
- A body the server refuses, such as a missing `email`, is 422 `invalid_parameter` with `param` naming the field.

Also available in: API [`POST /signups`](https://nextmail.sh/docs/api/reference/sign-up#post-signups); TypeScript [`signups.create()`](https://nextmail.sh/docs/sdk/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

```python
def verify(
    sign_up_id: str,
    code: str,
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> 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 sends no credential and returns 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`.

Sends no credential.

**Parameters**

- `sign_up_id` (`str`, required): The `id` `create` returned.
- `code` (`str`, required): The six digits from the email the person received.
- `api_key` (`str`): Ignored and never sent. Finishing a sign-up needs no credential.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `NextmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`SignUpAccountResource`, a dict with `object` set to `sign_up_account`, `id`, `userId`, `email`, `name`, `workspaceId`, the free `address` or `None`, and `apiKey`, a `SignUpApiKey` with `id`, `name`, `scopes` and the one-time `token`.

**Example**

```python
from pathlib import Path

from nextmail import nextmail

signups = create_signups()

sign_up = signups.create({'email': 'ada@example.com', 'agent': 'Claude Code'})
code = input(f'The code sent to {sign_up["sentTo"]}: ')

account = signups.verify(sign_up['id'], code)

Path('nextmail-api-key').write_text(account['apiKey']['token'])

print('Signed up', account['email'], 'with the address', account['address'])
```

**Notes**

- Call it on `create_signups()`, which needs no key, then build a `Nextmail` 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.
- A code that is not six digits is 422 `invalid_parameter`, and one network may check 30 codes every 10 minutes across all sign-ups before 429 `sign_up_rate_limited`.

Also available in: API [`POST /signups/{id}/verify`](https://nextmail.sh/docs/api/reference/sign-up#post-signups-id-verify); TypeScript [`signups.verify()`](https://nextmail.sh/docs/sdk/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).