--- title: "client.signups" description: "Every method in this namespace: its signature, its parameters, what it returns and an example." url: "https://nextmail.sh/docs/ruby/reference/signups" area: "Ruby" 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 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 ```ruby create(body = nil, api_key: nil, **fields) -> Hash ``` 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: no API key is sent, even when the client holding this namespace has 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** - `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` (`Array`): The scopes the key may hold, such as `emails:send`. Every scope when it is left out. - `api_key` (`String`): Ignored and never sent. Starting a sign-up is anonymous. **Returns** A Hash with `object` set to `sign_up`, the `id` to pass to `verify`, `sentTo`, the masked address the code went to, and `expiresAt`. **Example** ```ruby signups = Nextmail.create_signups sign_up = signups.create(email: "ada@example.com", name: "Ada Lovelace", agent: "Claude Code") puts "Ask for the code sent to #{sign_up[:sentTo]}" ``` **Notes** - Call it on `Nextmail.create_signups`, which needs no key. A client made with `Nextmail.create_client` or `Nextmail::Client.new` 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); 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 ```ruby verify(sign_up_id, code, api_key: nil) -> Hash ``` 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 and returns one: the token at `[: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` (`String`, required): The `id` that `create` returned. - `code` (`String`, required): The six digits from the email the person received. - `api_key` (`String`): Ignored and never sent. Finishing a sign-up is anonymous. **Returns** A Hash with `object` set to `sign_up_account`, `id`, `userId`, `email`, `name`, `workspaceId`, the free `address` or nil, and `apiKey`, a Hash with its `id`, `name`, `scopes` and one-time `token`. **Example** ```ruby signups = Nextmail.create_signups sign_up = signups.create(email: "ada@example.com", agent: "Claude Code") print "The code sent to #{sign_up[:sentTo]}: " account = signups.verify(sign_up[:id], gets.strip) client = Nextmail.create_client(account.dig(:apiKey, :token)) puts account[:address], client.me.get[:workspaceId] ``` **Notes** - Call it on `Nextmail.create_signups`, 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); 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).