User

Manage users within an account. Users are individuals who can log in and perform actions. Each account can have multiple users with different roles. Includes user creation with email verification, password management, suspension, and multi-factor authentication (MFA) setup.

Show my user details

GET

https://api.cakemail.dev

/users/self

Retrieve the profile of the currently authenticated user, including name, email, language, timezone, and activity timestamps.

Required scope(s): any_authenticated_pat

Show my user details › Responses

Successful Response

UserResponse

UserFullResponse · required

Forgot my password

POST

https://api.cakemail.dev

/users/forgot-my-password

Sends an email containing a reset password token.

Forgot my password › query Parameters

account_id

integer · min: 1

language

string · enum

Supported Locales

Enum values:

da_DK

de_DE

el_GR

en_US

Default: en_US

Forgot my password › Request Body

ForgotMyPassword

email

string · email · required

Email address of the user requesting a password reset

Forgot my password › Responses

Successful Response

ResetPasswordResponse

email

string · required

object

string

Default: user

reset_link_sent

boolean

Default: true

Reset my password

POST

https://api.cakemail.dev

/users/self/reset-password

Sends an email containing a reset password token.

Required scope(s): account:write

Reset my password › Responses

Successful Response

ResetPasswordResponse

email

string · required

object

string

Default: user

reset_link_sent

boolean

Default: true

Reset a user password

POST

https://api.cakemail.dev

/users/{user_id}/reset-password

Sends an email containing a reset password token.

Required scope(s): users:admin

Reset a user password › path Parameters

user_id

integer · required

Reset a user password › query Parameters

account_id

integer

Reset a user password › Request Body

ResetUserPassword

invalidate_current_password

boolean

If true, immediately invalidates the current password, forcing the user to reset

Default: false

Reset a user password › Responses

Successful Response

ResetPasswordResponse

email

string · required

object

string

Default: user

reset_link_sent

boolean

Default: true

Reset password confirmation

POST

https://api.cakemail.dev

/users/reset-password-confirm

Change a user password if the reset password token is valid for that user.

Reset password confirmation › Request Body

ResetPasswordConfirm

token

string · required

Password reset token received via email

password

string · minLength: 8 · maxLength: 128 · required

New password to set

Reset password confirmation › Responses

Successful Response

ResetPasswordConfirmResponse

object

string

Default: user

password_reset

boolean

Default: true

Show all users in my account

GET

https://api.cakemail.dev

/users

List all users in the authenticated user's account. Results can be filtered by status (active, suspended, or pending) and by email address. Pending users are those who have been invited but have not yet confirmed their account.

Required scope(s): users:read

Show all users in my account › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

page

integer · min: 1

Default: 1

per_page

integer · min: 1

Default: 50

with_count

boolean

Include count in the response

Default: false

filter

string

Valid Terms:

email
status

Valid Operators:

==

Query separator:

Valid Terms:

email
status

Valid Operators:

==

Query separator:

Show all users in my account › Responses

Successful Response

UsersResponse

Pagination · required

UserSummaryResponse[] · required

Create a user

POST

https://api.cakemail.dev

/users

Create a new user in the account. By default, the user is created in a pending state and a verification email is sent. The user must confirm their account by following the link in the email and setting a password.

Accounts with the appropriate permissions can skip email verification and create confirmed users directly by providing a password in the request.

Required scope(s): users:write

Create a user › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

skip_verification

boolean

Default: false

Create a user › Request Body

User

first_name

string · required

First name

last_name

string · required

Last name

email

string · email · required

Email address, used as the login username

title

string

Job title

office_phone

string

Office phone number

mobile_phone

string · pattern: [0-9]+

Mobile phone number (digits only)

language

string · enum

Preferred language (e.g. en_US, fr_FR)

Enum values:

da_DK

de_DE

el_GR

en_US

timezone

string

IANA timezone identifier (e.g. America/Montreal)

password

string · minLength: 8 · maxLength: 128

Password (only when creating confirmed users with skip_verification permission)

password_strength_requirement

string · enum

Minimum entropy requirement for the password

Enum values:

VERY_WEAK

WEAK

MODERATE

STRONG

VERY_STRONG

Default: VERY_WEAK

Create a user › Responses

Successful Response

CreateUserResponse

id

string · required

UserFullResponse · required

object

string

Default: user

created

boolean

Default: true

POST/users

curl https://api.cakemail.dev/users \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "first_name": "first_name",
  "last_name": "last_name",
  "title": "title",
  "office_phone": "office_phone",
  "mobile_phone": "mobile_phone",
  "language": "da",
  "timezone": "timezone",
  "password": "password",
  "email": "test@example.com",
  "password_strength_requirement": "VERY_WEAK"
}'

Example Request Body

{
  "first_name": "first_name",
  "last_name": "last_name",
  "title": "title",
  "office_phone": "office_phone",
  "mobile_phone": "mobile_phone",
  "language": "da",
  "timezone": "timezone",
  "password": "password",
  "email": "test@example.com",
  "password_strength_requirement": "VERY_WEAK"
}

json

Example Responses

{
  "id": "id",
  "object": "user",
  "created": true,
  "data": {
    "id": "id",
    "email": "email",
    "status": "status",
    "created_on": 0,
    "last_activity_on": 0,
    "expires_on": 0,
    "first_name": "first_name",
    "last_name": "last_name",
    "title": "title",
    "language": "da",
    "timezone": "timezone",
    "office_phone": "office_phone",
    "mobile_phone": "mobile_phone"
  }
}

json

application/json

Show a user details

GET

https://api.cakemail.dev

/users/{user_id}

Retrieve a user's details by ID. Accepts both confirmed user IDs (numeric) and pending user IDs (alphanumeric). Pending users are those who have been invited but have not yet completed email verification.

Required scope(s): users:read

Show a user details › path Parameters

user_id

string · minLength: 1 · maxLength: 20 · pattern: ^[a-zA-Z0-9]+$ · required

Show a user details › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Show a user details › Responses

Successful Response

UserResponse

UserFullResponse · required

Update a user

PATCH

https://api.cakemail.dev

/users/{user_id}

Update a user's profile. All fields are optional — only provided fields are updated. To change a password, the user's current password must be verified unless the caller has admin-level override permissions.

Required scope(s): users:write

Update a user › path Parameters

user_id

string · minLength: 1 · maxLength: 20 · pattern: ^[a-zA-Z0-9]+$ · required

Update a user › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Update a user › Request Body

PatchUser

first_name

string

last_name

string

title

string

Job title

office_phone

string

Office phone number

mobile_phone

string · pattern: [0-9]+

Mobile phone number (digits only)

language

string · enum

Preferred language (e.g. en_US, fr_FR)

Enum values:

da_DK

de_DE

el_GR

en_US

timezone

string

IANA timezone identifier (e.g. America/Montreal)

ChangePassword

Update a user › Responses

Successful Response

PatchUserResponse

id

string · required

UserFullResponse · required

object

string

Default: user

patched

boolean

Default: true

PATCH/users/{user_id}

curl https://api.cakemail.dev/users/:user_id \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "first_name": "first_name",
  "last_name": "last_name",
  "title": "title",
  "office_phone": "office_phone",
  "mobile_phone": "mobile_phone",
  "language": "da",
  "timezone": "timezone",
  "password": {
    "current": "current",
    "new": "newaaaaa",
    "password_strength_requirement": "VERY_WEAK"
  }
}'

Example Request Body

{
  "first_name": "first_name",
  "last_name": "last_name",
  "title": "title",
  "office_phone": "office_phone",
  "mobile_phone": "mobile_phone",
  "language": "da",
  "timezone": "timezone",
  "password": {
    "current": "current",
    "new": "newaaaaa",
    "password_strength_requirement": "VERY_WEAK"
  }
}

json

Example Responses

{
  "id": "id",
  "object": "user",
  "patched": true,
  "data": {
    "id": "id",
    "email": "email",
    "status": "status",
    "created_on": 0,
    "last_activity_on": 0,
    "expires_on": 0,
    "first_name": "first_name",
    "last_name": "last_name",
    "title": "title",
    "language": "da",
    "timezone": "timezone",
    "office_phone": "office_phone",
    "mobile_phone": "mobile_phone"
  }
}

json

application/json

Delete a user

DELETE

https://api.cakemail.dev

/users/{user_id}

Delete a user from the account. Works for both confirmed users (numeric ID) and pending users (alphanumeric ID) who have not yet completed verification.

Required scope(s): users:admin

Delete a user › path Parameters

user_id

string · minLength: 1 · maxLength: 20 · pattern: ^[a-zA-Z0-9]+$ · required

Delete a user › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Delete a user › Responses

Successful Response

DeleteUserResponse

id

string · required

object

string

Default: user

deleted

boolean

Default: true

Suspend a user

POST

https://api.cakemail.dev

/users/{user_id}/suspend

Suspend a user, preventing them from logging in or performing any actions. The user's data is preserved and can be restored by unsuspending.

Required scope(s): users:admin

Suspend a user › path Parameters

user_id

integer · required

Suspend a user › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Suspend a user › Responses

Successful Response

SuspendUserResponse

id

string · required

UserFullResponse · required

object

string

Default: user

suspended

boolean

Default: true

Unsuspend a user

POST

https://api.cakemail.dev

/users/{user_id}/unsuspend

Restore a previously suspended user, allowing them to log in and perform actions again.

Required scope(s): users:admin

Unsuspend a user › path Parameters

user_id

integer · required

Unsuspend a user › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Unsuspend a user › Responses

Successful Response

SuspendUserResponse

id

string · required

UserFullResponse · required

object

string

Default: user

suspended

boolean

Default: true

Confirm a user

POST

https://api.cakemail.dev

/users/{user_id}/confirm

Confirm a pending user using the confirmation hash from the verification email. The user must set a password that meets the account's strength requirements. Once confirmed, the user can log in and access the platform.

Confirm a user › path Parameters

user_id

string · minLength: 1 · maxLength: 20 · pattern: ^[a-zA-Z0-9]+$ · required

Confirm a user › Request Body

UserConfirmation

confirmation

string · required

Confirmation hash from the verification email

password

string · minLength: 8 · maxLength: 128 · required

Password to set for the new account

Confirm a user › Responses

Successful Response

ConfirmUserResponse

id

string · required

UserFullResponse · required

object

string

Default: user

confirmed

boolean

Default: true

POST/users/{user_id}/confirm

curl https://api.cakemail.dev/users/:user_id/confirm \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "confirmation": "confirmation",
  "password": "password"
}'

Example Request Body

{
  "confirmation": "confirmation",
  "password": "password"
}

json

Example Responses

{
  "id": "id",
  "object": "user",
  "confirmed": true,
  "data": {
    "id": "id",
    "email": "email",
    "status": "status",
    "created_on": 0,
    "last_activity_on": 0,
    "expires_on": 0,
    "first_name": "first_name",
    "last_name": "last_name",
    "title": "title",
    "language": "da",
    "timezone": "timezone",
    "office_phone": "office_phone",
    "mobile_phone": "mobile_phone"
  }
}

json

application/json

Resend the user verification email

POST

https://api.cakemail.dev

/users/{user_id}/resend-verification-email

Resend the verification email to a pending user who has not yet confirmed their account. Rate-limited to prevent abuse.

Resend the user verification email › path Parameters

user_id

string · minLength: 1 · maxLength: 20 · pattern: ^[a-zA-Z0-9]+$ · required

Resend the user verification email › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

Resend the user verification email › Responses

Successful Response

ResendUserVerificationEmailResponse

object

string

Default: user

confirmation_resent

boolean

Default: true

List active MFA methods

GET

https://api.cakemail.dev

/users/self/mfa

List all multi-factor authentication methods configured for the authenticated user, including their type and activation status.

Required scope(s): account:read

List active MFA methods › query Parameters

page

integer · min: 1

Default: 1

per_page

integer · min: 1

Default: 50

with_count

boolean

Include count in the response

Default: false

List active MFA methods › Responses

Successful Response

ListMFAResponse

object · required

Pagination details

MFAResponse[] · required

List of MFA methods

Attach an MFA method

POST

https://api.cakemail.dev

/users/self/mfa

Register a new MFA method for the authenticated user. Currently supports TOTP (time-based one-time password) via authenticator apps. Returns a QR code and secret key for setup. The method must be activated with a valid code before it takes effect.

Required scope(s): account:write

Attach an MFA method › Request Body

CreateMFARequest

type

MFAType · enum · required

An enumeration.

Enum values:

totp

description

string

Attach an MFA method › Responses

Successful Response

CreateMFAResponse

id

string · required

MFA method id

object · required

Created MFA method details

object

string

Object type

Default: mfa

created

boolean

Whether the MFA method was created

Default: true

Activate an MFA method

POST

https://api.cakemail.dev

/users/self/mfa/{mfa_id}/activate

Activate a previously registered MFA method by verifying a code generated by the authenticator app. Once activated, the user will be required to complete an MFA challenge on every login.

Required scope(s): account:write

Activate an MFA method › path Parameters

mfa_id

string · required

Activate an MFA method › Request Body

ActivateMFARequest

code

string · minLength: 6 · maxLength: 6 · pattern: ^[0-9]+$ · required

6 digit code from this MFA method

Activate an MFA method › Responses

Successful Response

ActivateMFAResponse

id

string · required

MFA method id

object

string

Object type

Default: mfa

activated

boolean

Whether the MFA method was activated

Default: true

Get MFA recovery codes

GET

https://api.cakemail.dev

/users/self/mfa-recovery-codes

Retrieve the MFA recovery codes for the authenticated user. Recovery codes are single-use codes that can be used to log in if the user loses access to their authenticator app. Each code is a 12-character hexadecimal string.

Required scope(s): account:read

Get MFA recovery codes › Responses

Successful Response

RecoveryCodesResponse

data

string[] · required

List of recovery codes

Get the MFA portal URL

GET

https://api.cakemail.dev

/users/self/mfa-portal

Get a URL to the MFA management portal where the user can manage their authentication methods. Optionally provide a return_url to redirect the user back after they complete their changes.

Required scope(s): account:read

Get the MFA portal URL › query Parameters

return_url

string · uri · minLength: 1 · maxLength: 2083

Get the MFA portal URL › Responses

Successful Response

GetMFAPortalResponse

url

string · uri · minLength: 1 · maxLength: 2083 · required

MFA portal URL

Remove an MFA method

DELETE

https://api.cakemail.dev

/users/self/mfa/{mfa_id}

Remove an MFA method from the authenticated user's account. If this is the user's only active MFA method, MFA will be disabled for their account.

Required scope(s): account:write

Remove an MFA method › path Parameters

mfa_id

string · required

Remove an MFA method › Responses

Successful Response

DeleteMFAResponse

id

string · required

MFA method id

object

string

Object type

Default: mfa

deleted

boolean

Whether the MFA method was deleted

Default: true

Account List