$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 and sends no credential for it: 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. Nextmail::createSignups() reaches them without an API key.
signups->create
Start creating an account for a person
create(array $body, ?string $apiKey = null): arrayStarts 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, so call it on Nextmail::createSignups(), which holds none, and it sends none 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 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 retryAfterSeconds set on the exception. When the email cannot be sent it is 503 sign_up_undeliverable and no sign-up is waiting.
Parameters
emailstringRequiredThe address the account signs in with. The code goes there, so it has to be one the person reads.
namestringThe name of the person the account is for. The address stands in when it is left out.
agentstringWho is asking, such as
Claude Code. The emails name it, and the key is named after it.scopesstring[]What the key may do, from
Nextmail\Constants\ApiScopes. Every scope when it is left out.apiKeystringIgnored and never sent. Starting a sign-up is anonymous.
Returns
An array with object set to sign_up, the id to pass to signups->verify, sentTo, the masked address the code went to, and expiresAt, when the code runs out.
Example
use Nextmail\Exception\ApiException;use Nextmail\Nextmail; $signups = Nextmail::createSignups(); try { $signUp = $signups->create([ 'email' => '[email protected]', 'name' => 'Ada Lovelace', 'agent' => 'Claude Code', ]); echo 'Ask for the code sent to ', $signUp['sentTo'], PHP_EOL;} catch (ApiException $error) { if ($error->errorCode !== 'sign_up_address_refused') { throw $error; } echo 'That address cannot receive the code, so ask for another one', PHP_EOL;}Notes
Call it on
Nextmail::createSignups(), which needs no key. A client made withNextmail::createClient()ornew 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
scopeslists fewer, and the person can narrow the key later in Settings, API keys.
Also available in
- API
POST /signups- TypeScript
signups.create()- Python
signups.create()- Ruby
signups.create- Go
Signups.Create- Java
signups().create- C#
Signups.CreateAsync- CLI
nextmail signups create
signups->verify
Finish a sign-up with the code and get the key
verify(string $signUpId, string $code, ?string $apiKey = null): arraySends 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, so call it on Nextmail::createSignups(), and it 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.
Parameters
signUpIdstringRequiredThe
idsignups->createreturned, such assgn_4f1c9a7e2b3d8c60a5e1f2d3.codestringRequiredThe six digits from the email the person received.
apiKeystringIgnored and never sent. Finishing a sign-up is anonymous.
Returns
An array with object set to sign_up_account, the sign-up id, userId, email, name, workspaceId, the free address or null, and apiKey, an array with object set to api_key, id, name, scopes and the one-time token.
Example
use Nextmail\Nextmail; $signups = Nextmail::createSignups(); $account = $signups->verify('sgn_4f1c9a7e2b3d8c60a5e1f2d3', trim((string) readline('Code from the email: '))); $key = $account['apiKey']; echo 'Created ', $account['email'], ' in ', $account['workspaceId'], PHP_EOL;echo 'Store the token of ', $key['name'], ' now, it is never shown again', PHP_EOL;Notes
Call it on
Nextmail::createSignups(), which needs no key, then build a client with the key it returns,new Nextmail($account['apiKey']['token']), or pass the token asapiKey:on a single call.Not retried automatically, since the code works once.
The key starts with every scope unless the sign-up asked for fewer.
Google Workspace