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

# client.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 tells it the six-digit code emailed to them, and finishing the sign-up returns an API key for the new account. `NextmailClient.CreateSignups()` reaches them without an API key, and neither call sends the credential of a client.

### `Signups.CreateAsync`

Start creating an account for a person

```csharp
Task<JsonObject> CreateAsync(
    IReadOnlyDictionary<string, object?> body,
    string? apiKey = null,
    CancellationToken cancellationToken = default)
```

Starts a sign-up for an address and emails it a six-digit code that works once and runs out after 10 minutes. It takes no credential at all, so call it on `NextmailClient.CreateSignups()`, which needs none, and it sends no API key or access token even from a client that holds one. Ask the person for the code, then finish with `Signups.VerifyAsync`, 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**

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

**Returns**

A `JsonObject` with `object` set to `sign_up`, the `id` to finish with, `sentTo`, the masked address the code went to, and `expiresAt`.

**Example**

```csharp
using Nextmail.Constants;

var signups = NextmailClient.CreateSignups();

var signUp = await signups.CreateAsync(new Body
{
    ["email"] = "ada@example.com",
    ["name"] = "Ada Lovelace",
    ["agent"] = "Claude Code",
    ["scopes"] = new[] { ApiScopes.EmailsSend, ApiScopes.ThreadsRead },
});

await File.WriteAllTextAsync(".sign-up-id", (string?)signUp["id"]);

Console.WriteLine($"Ask for the code sent to {signUp["sentTo"]} before {signUp["expiresAt"]}");
```

**Notes**

- Call it on `NextmailClient.CreateSignups()`, which needs no key. A client made with `new NextmailClient` 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); TypeScript [`signups.create()`](https://nextmail.sh/docs/sdk/reference/signups#create); 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); CLI [`nextmail signups create`](https://nextmail.sh/docs/cli/reference/signups#signups-create).

### `Signups.VerifyAsync`

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

```csharp
Task<JsonObject> VerifyAsync(
    string signUpId,
    string code,
    string? apiKey = null,
    CancellationToken cancellationToken = default)
```

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 takes no credential, so call it on `NextmailClient.CreateSignups()` as well, 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**

- `signUpId` (`string`, required): The `id` `Signups.CreateAsync` returned.
- `code` (`string`, required): The six digits from the email the person received.
- `apiKey` (`string?`): Ignored and never sent. Finishing a sign-up is anonymous.
- `cancellationToken` (`CancellationToken`): Cancels the request.

**Returns**

A `JsonObject` with `object` set to `sign_up_account`, `id`, `userId`, `email`, `name`, `workspaceId`, the free `address` or null, and `apiKey` with its `id`, `name`, `scopes` and one-time `token`.

**Example**

```csharp
var signups = NextmailClient.CreateSignups();

Console.Write("Code from the email: ");

try
{
    var account = await signups.VerifyAsync("sgn_k7m2q9xw4bdp", Console.ReadLine()?.Trim() ?? string.Empty);

    await File.WriteAllTextAsync(".nextmail-api-key", (string?)account["apiKey"]?["token"]);

    Console.WriteLine($"Created the account for {account["email"]} with the address {(string?)account["address"] ?? "none yet"}");
}
catch (NextmailApiException error)
{
    if (error.Code != "sign_up_code_invalid")
    {
        throw;
    }

    Console.WriteLine(error.Message);
}
```

**Notes**

- Call it on `NextmailClient.CreateSignups()`, which needs no key, then build a client with the key it returns: pass `apiKey.token` as `ApiKey` in `NextmailOptions`, or straight to `new NextmailClient`.
- 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); TypeScript [`signups.verify()`](https://nextmail.sh/docs/sdk/reference/signups#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); CLI [`nextmail signups verify`](https://nextmail.sh/docs/cli/reference/signups#signups-verify).