Sign-up
Every operation in this group: what it accepts, what it returns and the errors it can answer with.
Operations
An agent creates an account on Nextmail for a person, and the person supplies one thing: the six-digit code emailed to them. Neither call takes a credential, and the second one returns an API key, so a program goes from nothing to a working key in two requests. The account is the person's: it signs in with their address, gets the same free plan, free address and limits as any other, and they set a password from the welcome email. An address that already has an account is never signed in to this way, and the answer does not reveal that it has one.
POST/signups
Start a sign-up
Takes no credential. Checks the address, then emails it a six-digit code that works once and runs out after 10 minutes, and answers with the id to finish with. Ask the person for the code, then call POST /signups/{id}/verify.
An address that cannot receive mail, or one on a disposable domain, is refused with sign_up_address_refused and nothing is sent. When the address already has an account, no code is sent: that person gets an email saying 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 tells anyone 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 a 429 sign_up_rate_limited with Retry-After.
Request body
emailstringRequiredThe address the account signs in with. The six-digit code goes there, so it has to be an address the person reads.
3 to 254 charactersnamestringThe name of the person the account is for. The address stands in when it is left out.
Up to 80 charactersagentstringWho is asking, such as
Claude Code. The emails name it, and the key it gets is named after it.Up to 60 charactersscopesstring[]What the key may do. Every scope when it is left out.
At least one itemOne of"emails:send""emails:read""drafts:read""drafts:write""threads:read""threads:write""files:read""files:write""labels:read""labels:write""contacts:read""contacts:write""audiences:read""audiences:write""calendar:read""calendar:write""templates:read""templates:write""domains:read""domains:write""webhooks:read""webhooks:write""rules:read""rules:write""connections:read""members:read""members:write""roles:read""roles:write""settings:read""settings:write""keys:write""keys:read""keys:manage""forms:read""forms:write""knowledge:read""knowledge:write""automations:read""automations:write""tasks:read""tasks:write""connectors:read""connectors:use""connectors:write""billing:read""billing:write""account:read""account:write"
Returns
The sign-up, waiting for its code.
Errors
- 400
- 422
sign_up_address_refused, orinvalid_parameterfor a body the schema refuses, withparamnaming the field.- 503
sign_up_undeliverable: the email could not be sent, and no sign-up is waiting.
The errors every operation can return500Error catalog
Also available in
- TypeScript
signups.create()- Python
signups.create()- Ruby
signups.create- PHP
signups->create- Go
Signups.Create- Java
signups().create- C#
Signups.CreateAsync- CLI
nextmail signups create
POST/signups/{id}/verify
Finish a sign-up
Takes no credential and returns one. Send the 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, with every scope unless the sign-up asked for fewer. 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, where they can narrow or remove it.
A sign-up takes 5 codes. A wrong one is a 400 sign_up_code_invalid whose message says how many tries are left, 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 a 400 sign_up_code_expired. One network may check 30 codes every 10 minutes across all sign-ups.
Path parameters
idstringRequiredThe
idPOST /signupsanswered with.
Request body
codestringRequiredThe six-digit code from the email the person received.
Pattern^\d{6}$
Returns
The account, its workspace and free address, and its key, shown only here.
Errors
- 409
sign_up_address_taken: the address got an account while the code was waiting.- 422
invalid_parameterfor a code that is not six digits, withparamnaming it.- 429
sign_up_locked, orsign_up_rate_limitedwithRetry-After.
The errors every operation can return500Error catalog
Also available in
- TypeScript
signups.verify()- Python
signups.verify()- Ruby
signups.verify- PHP
signups->verify- Go
Signups.Verify- Java
signups().verify- C#
Signups.VerifyAsync- CLI
nextmail signups verify
Objects
SignUpobject
objectstringRequired- One of
"sign_up" idstringRequiredFinish the sign-up with this id.
sentTostringRequiredThe address the code went to, masked, to show the person where to look.
expiresAtstringRequiredWhen the code runs out, 10 minutes after it was sent.
Formatdate-time
SignUpAccountobject
objectstringRequired- One of
"sign_up_account" idstringRequiredThe id of the sign-up this finished.
userIdstringRequiredThe new account.
emailstringRequiredThe address the account signs in with.
namestringRequiredThe name on the account.
workspaceIdstringRequiredThe workspace the account owns, and the key belongs to.
addressstringRequiredThe free address the account got, or null while none can be given out.
Can be nullapiKeySignUpApiKeyRequired
SignUpApiKeyobject
objectstringRequired- One of
"api_key" idstringRequirednamestringRequiredThe agent that asked, or
Agentwhen it gave no name.scopesstring[]RequiredWhat the key may do.
tokenstringRequiredThe secret, shown only in this answer. Send it as
Authorization: Bearer <token>. It works until the person revokes it.
Google Workspace