--- title: "client.signups()" description: "Every method in this namespace: its signature, its parameters, what it returns and an example." url: "https://nextmail.sh/docs/java/reference/signups" area: "Java" category: "Reference" --- # client.signups() Every method in this namespace: its signature, its parameters, what it returns and an example. ## Methods Create an account for a person with no credential at all: start a sign-up for their address, ask them for the six-digit code emailed to them, and finish the sign-up to get an API key for the new account. `Nextmail.createSignups()` reaches them without an API key. ### `signups().create` Start creating an account for a person ```java Map create(Map body, RequestOptions options) ``` 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 `signups().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 answers 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` (`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` (`List`): What the key may do, each one of `sh.nextmail.constants.ApiScopes`. Every scope when it is left out. - `options.apiKey` (`String`): Ignored and never sent. Starting a sign-up is anonymous. **Returns** A map with `object` set to `sign_up`, the `id` to pass to `signups().verify`, `sentTo`, the masked address the code went to, and `expiresAt`. **Example** ```java Signups signups = Nextmail.createSignups(); Map signUp = signups.create(Body.of( "email", "ada@example.com", "name", "Ada Lovelace", "agent", "Claude Code", "scopes", List.of(ApiScopes.EMAILS_SEND, ApiScopes.THREADS_READ) )); System.out.println("Ask for the code sent to " + signUp.get("sentTo") + ", then verify " + signUp.get("id")); ``` **Notes** - Call it on `Nextmail.createSignups()`, which needs no key. A client made with `new Nextmail(apiKey)` or `Nextmail.builder()` needs one, and an agent signing up has none yet. To set a base URL, a timeout or an HTTP client, finish `Nextmail.builder()` with `buildSignups()` instead. - 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 that is not valid JSON is 400 `malformed_json`, and a field that is missing or not valid is 422 `invalid_parameter`. 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); 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 ```java Map verify(String signUpId, String code, RequestOptions options) ``` 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** - `signUpId` (`String`, required): The `id` that `signups().create` returned. - `code` (`String`, required): The six digits from the email the person received. - `options.apiKey` (`String`): Ignored and never sent. Finishing a sign-up is anonymous. **Returns** A map with `object` set to `sign_up_account`, `id`, `userId`, `email`, `name`, `workspaceId`, the free `address` or null, and `apiKey`, a map with `object` set to `api_key`, `id`, `name`, `scopes` and the one-time `token`. Pass the token to `new Nextmail(token)` to act for the new account. **Example** ```java Signups signups = Nextmail.createSignups(); Map signUp = signups.create(Body.of("email", "ada@example.com", "agent", "Claude Code")); Map account = signups.verify((String) signUp.get("id"), "123456"); Object token = account.get("apiKey") instanceof Map apiKey ? apiKey.get("token") : null; System.out.println(account.get("workspaceId") + " " + account.get("address") + " " + token); ``` **Notes** - Call it on `Nextmail.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); 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); C# [`Signups.VerifyAsync`](https://nextmail.sh/docs/csharp/reference/signups#verify); CLI [`nextmail signups verify`](https://nextmail.sh/docs/cli/reference/signups#signups-verify).