> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/users/module-2/email.md).

# Email

Email management endpoints

## Get Primary Email

> Retrieves the user's primary email address.

```json
{"openapi":"3.1.0","info":{"title":"User API","version":"1.0.0"},"tags":[{"name":"Email","description":"Email management endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[{"cookieAuth":[]}],"components":{"securitySchemes":{"cookieAuth":{"type":"apiKey","in":"cookie","name":"sessionid"}},"schemas":{"UserEmail":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the email address. Read-only."},"user":{"type":"integer","description":"Identifier of the owning user. Ignored on input — the endpoint always uses the authenticated user. Read-only."},"email":{"type":"string","format":"email","description":"The email address. Required when adding a new email."},"verified":{"type":"boolean","description":"Indicates if the email address has been verified. Read-only."},"primary":{"type":"boolean","description":"Indicates if this is the primary email address for the user. Read-only."}}}}},"paths":{"/users/email-change/":{"get":{"tags":["Email"],"summary":"Get Primary Email","description":"Retrieves the user's primary email address.","operationId":"getPrimaryEmail","responses":{"200":{"description":"Primary email details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserEmail"}}}}}}}}}
```

## Request Email Change

> Initiates a request to change the user's primary email address.\
> \
> \*\*Business Logic:\*\*\
> \- \*\*Verification:\*\* Requires the user's current password to authorize the change.\
> \- \*\*Notifications:\*\*\
> &#x20; \- Sends a \*\*confirmation email\*\* to the new email address.\
> &#x20; \- Sends a \*\*confirmation SMS\*\* to the user's registered phone number.\
> \-         \*\*URL Format:\*\* The notifications contain a signed URL pointing to the \`/users/email-set-primary/{signed\_email}/{user\_id\_key}/\` endpoint.\
> \
> \*\*Dynamic Settings:\*\*\
> \- \`NO\_REPLY\_EMAIL\`: Sender address for the email.\
> \
> \*\*Notes:\*\*\
> \- The signed link is valid for \*\*7 days\*\*.\
> \- The address does \*\*not\*\* change here. It changes when the confirmation\
> &#x20; link is visited (\`/users/email-set-primary/...\`).\
> \
> \*\*Optional step-up gate (second factor):\*\*\
> When \`EMAIL\_CHANGE\_VIEW\` routes this endpoint to\
> \`omnishop.users.views.SecureEmailChangeView\` \*\*and\*\* the \`email-change\`\
> purpose is enabled in \`VERIFICATION\_TOKEN\_CONF\`, the request additionally\
> requires an OTP proof on top of the password:\
> \
> \- Call it once without factors to discover what is missing: the response\
> &#x20; is \`406\` with \`error\_code: verification\_100\_3\` and a \`step\_up\` payload\
> &#x20; listing the unmet factors. Drive the UI from that list instead of\
> &#x20; hardcoding "password then OTP" — whether the gate is live is per-brand\
> &#x20; configuration.\
> \- Run the OTP flow (\`POST /users/verification/init/\` then\
> &#x20; \`/users/verification/verify/\`, see the Verification & Step-up API\
> &#x20; document) with \`purpose: "email-change"\` and \`target\` set to the new\
> &#x20; address, then retry this request with the returned token in the\
> &#x20; \`X-Verification-Token\` header.\
> \- The \`email\` submitted here must equal the \`target\` the token was issued\
> &#x20; for; otherwise the token is refused as if none had been supplied.\
> \- A wrong password does not consume the token — retry with the correct\
> &#x20; password using the same one.\
> \- With \`EMAIL\_CHANGE\_VIEW\` set to\
> &#x20; \`omnishop.users.views.OtpOnlyEmailChangeView\` (meant for brands with\
> &#x20; passwordless sign-up), every account is asked for the OTP proof only:\
> &#x20; \`password\` is not required and the \`step\_up\` payload lists \`otp\`\
> &#x20; alone.\
> \
> With \`EMAIL\_CHANGE\_VIEW\` unset, or the purpose disabled, the legacy\
> password-only behaviour is served and no \`step\_up\` payload is ever\
> returned.

```json
{"openapi":"3.1.0","info":{"title":"User API","version":"1.0.0"},"tags":[{"name":"Email","description":"Email management endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[{"cookieAuth":[]}],"components":{"securitySchemes":{"cookieAuth":{"type":"apiKey","in":"cookie","name":"sessionid"}},"parameters":{"CSRFTokenHeader":{"name":"X-CSRFToken","in":"header","description":"CSRF token for write operations (POST, PUT, PATCH, DELETE).\nRequired for security when using session authentication.\nObtain token from cookie 'csrftoken' or meta tag in HTML.","required":true,"schema":{"type":"string"}},"CookieHeader":{"name":"Cookie","in":"header","description":"Session ID and CSRF token cookies.\nFormat: `sessionid=<id>; osessionid=<id>; csrftoken=<token>`","required":true,"schema":{"type":"string"}},"VerificationTokenHeader":{"name":"X-Verification-Token","in":"header","required":false,"description":"Single-use verification token from `POST /users/verification/verify/`\n(see the Verification & Step-up API document). Required only where a\nstep-up gate is enabled, and omitted on the discovery call. Send it in\nthis header — it is the only supported location.","schema":{"type":"string"}}},"schemas":{"UserEmailChangeRequest":{"type":"object","required":["email","password"],"description":"Under the step-up gate the discovery call deliberately omits `password`\n(and the token): the gate answers `406` before the body is validated, so a\nrequest carrying only `email` is enough to learn which factors are needed.\n`password` is not required under `OtpOnlyEmailChangeView`.","properties":{"user":{"type":"integer","readOnly":true,"description":"Ignored on input — the endpoint always sets it to the authenticated\nuser. Echoed back in the response."},"email":{"type":"string","format":"email","description":"The new email address. Must be different from the current email and not already in use.\nUnder the step-up gate it must also equal the `target` the verification token was issued for."},"password":{"type":"string","format":"password","description":"The user's current password. Required for verification."}}},"ValidationErrorResponse":{"type":"object","description":"Standard DRF validation error response","additionalProperties":{"type":"array","items":{"type":"string"}}},"StepUpRequiredResponse":{"type":"object","description":"406 response of a step-up gated endpoint whose factors are not satisfied.\nDrive the UI from `step_up.required` — it lists only the unmet factors, and\n`allowed_channels` is already filtered for the factor-repetition rule (a\nstep-up code may not be sent over the channel the session signed in with).","properties":{"non_field_errors":{"type":"string"},"error_code":{"type":"string"},"step_up":{"type":"object","properties":{"purpose":{"type":"string"},"required":{"type":"array","description":"One entry per unmet factor. A `password` entry names the body field\nto collect; an `otp` entry carries the channels still allowed, the\nheader to send the token in, and the two endpoint URLs to run.","items":{"type":"object"}}}}}}}},"paths":{"/users/email-change/":{"post":{"tags":["Email"],"summary":"Request Email Change","description":"Initiates a request to change the user's primary email address.\n\n**Business Logic:**\n- **Verification:** Requires the user's current password to authorize the change.\n- **Notifications:**\n  - Sends a **confirmation email** to the new email address.\n  - Sends a **confirmation SMS** to the user's registered phone number.\n-         **URL Format:** The notifications contain a signed URL pointing to the `/users/email-set-primary/{signed_email}/{user_id_key}/` endpoint.\n\n**Dynamic Settings:**\n- `NO_REPLY_EMAIL`: Sender address for the email.\n\n**Notes:**\n- The signed link is valid for **7 days**.\n- The address does **not** change here. It changes when the confirmation\n  link is visited (`/users/email-set-primary/...`).\n\n**Optional step-up gate (second factor):**\nWhen `EMAIL_CHANGE_VIEW` routes this endpoint to\n`omnishop.users.views.SecureEmailChangeView` **and** the `email-change`\npurpose is enabled in `VERIFICATION_TOKEN_CONF`, the request additionally\nrequires an OTP proof on top of the password:\n\n- Call it once without factors to discover what is missing: the response\n  is `406` with `error_code: verification_100_3` and a `step_up` payload\n  listing the unmet factors. Drive the UI from that list instead of\n  hardcoding \"password then OTP\" — whether the gate is live is per-brand\n  configuration.\n- Run the OTP flow (`POST /users/verification/init/` then\n  `/users/verification/verify/`, see the Verification & Step-up API\n  document) with `purpose: \"email-change\"` and `target` set to the new\n  address, then retry this request with the returned token in the\n  `X-Verification-Token` header.\n- The `email` submitted here must equal the `target` the token was issued\n  for; otherwise the token is refused as if none had been supplied.\n- A wrong password does not consume the token — retry with the correct\n  password using the same one.\n- With `EMAIL_CHANGE_VIEW` set to\n  `omnishop.users.views.OtpOnlyEmailChangeView` (meant for brands with\n  passwordless sign-up), every account is asked for the OTP proof only:\n  `password` is not required and the `step_up` payload lists `otp`\n  alone.\n\nWith `EMAIL_CHANGE_VIEW` unset, or the purpose disabled, the legacy\npassword-only behaviour is served and no `step_up` payload is ever\nreturned.","operationId":"requestEmailChange","parameters":[{"$ref":"#/components/parameters/CSRFTokenHeader"},{"$ref":"#/components/parameters/CookieHeader"},{"$ref":"#/components/parameters/VerificationTokenHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserEmailChangeRequest"}}}},"responses":{"200":{"description":"Email change requested"},"400":{"description":"Validation error (e.g., email exists, invalid password)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"406":{"description":"Step-up gate only: a required factor is missing or unsatisfied. Also\nreturned when the supplied verification token has expired, was already\nconsumed, or is bound to a different `target` — an unusable token is\ntreated as no token at all, there is no distinct error code for it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StepUpRequiredResponse"}}}}}}}}}
```

## Revoke Email Change (Click-Through)

> Same operation as the \`POST\`, for the one-click link in the notice email.\
> The token travels as the \`token\` query parameter. If you route the link\
> through a frontend page, forward the value unchanged.

```json
{"openapi":"3.1.0","info":{"title":"User API","version":"1.0.0"},"tags":[{"name":"Email","description":"Email management endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[],"paths":{"/users/email-change/revoke/":{"get":{"tags":["Email"],"summary":"Revoke Email Change (Click-Through)","description":"Same operation as the `POST`, for the one-click link in the notice email.\nThe token travels as the `token` query parameter. If you route the link\nthrough a frontend page, forward the value unchanged.","operationId":"revokeEmailChangeClickThrough","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string"},"description":"Revoke token, taken verbatim from the link"}],"responses":{"200":{"description":"Change reverted (empty body)"},"406":{"$ref":"#/components/responses/EmailRevokeNotAllowed"},"429":{"$ref":"#/components/responses/Throttled"}}}}},"components":{"responses":{"EmailRevokeNotAllowed":{"description":"The revoke token is invalid, expired, or has already been used. One code\ncovers all three — the response does not distinguish them.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodedErrorResponse"}}}},"Throttled":{"description":"Request was throttled (scope rate limit exceeded).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailErrorResponse"}}}}},"schemas":{"CodedErrorResponse":{"type":"object","description":"Business-error payload, returned with HTTP 406. `error_code` is stable —\nbranch on it, not on the translated message.","properties":{"non_field_errors":{"type":"string"},"error_code":{"type":"string"}}},"DetailErrorResponse":{"type":"object","properties":{"detail":{"type":"string"}}}}}}
```

## Revoke Email Change (Kill-Switch)

> Restores the previous primary email address from the signed token\
> delivered to the OLD address after a completed change.\
> \
> \*\*Business Logic:\*\*\
> \- Single-use, and only valid within\
> &#x20; \`SECURE\_EMAIL\_CHANGE\_REVOKE\_WINDOW\_DAYS\` (default 7) of the change.\
> \- Unauthenticated by design: the token is the authorization, since the\
> &#x20; person clicking the link may have no session.\
> \- Sends a "change reverted" notice to the restored address.\
> \- Makes the account's current password \*\*unusable\*\* and starts the normal\
> &#x20; password-reset flow, mailing a reset link to the restored address. A\
> &#x20; revoke means the change is presumed to have been an attacker's, so the\
> &#x20; password it was made with can no longer be trusted; the notice tells the\
> &#x20; user this. Live sessions and the DRF auth token are left untouched.\
> \
> \*\*Notes:\*\*\
> \- The endpoint is always routed, but revoke tokens are only ever issued by\
> &#x20; \`SecureEmailChangeSetPrimaryView\` — i.e. when \`EMAIL\_SET\_PRIMARY\_VIEW\`\
> &#x20; points at it. Without that, no valid token exists and every call is\
> &#x20; refused with \`406\`.\
> \- Throttling scope: \`secure-email-change-revoke\` (10 per hour per IP).

```json
{"openapi":"3.1.0","info":{"title":"User API","version":"1.0.0"},"tags":[{"name":"Email","description":"Email management endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[],"paths":{"/users/email-change/revoke/":{"post":{"tags":["Email"],"summary":"Revoke Email Change (Kill-Switch)","description":"Restores the previous primary email address from the signed token\ndelivered to the OLD address after a completed change.\n\n**Business Logic:**\n- Single-use, and only valid within\n  `SECURE_EMAIL_CHANGE_REVOKE_WINDOW_DAYS` (default 7) of the change.\n- Unauthenticated by design: the token is the authorization, since the\n  person clicking the link may have no session.\n- Sends a \"change reverted\" notice to the restored address.\n- Makes the account's current password **unusable** and starts the normal\n  password-reset flow, mailing a reset link to the restored address. A\n  revoke means the change is presumed to have been an attacker's, so the\n  password it was made with can no longer be trusted; the notice tells the\n  user this. Live sessions and the DRF auth token are left untouched.\n\n**Notes:**\n- The endpoint is always routed, but revoke tokens are only ever issued by\n  `SecureEmailChangeSetPrimaryView` — i.e. when `EMAIL_SET_PRIMARY_VIEW`\n  points at it. Without that, no valid token exists and every call is\n  refused with `406`.\n- Throttling scope: `secure-email-change-revoke` (10 per hour per IP).","operationId":"revokeEmailChange","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeRequest"}}}},"responses":{"200":{"description":"Change reverted; the previous address is primary again (empty body)"},"400":{"description":"`revoke_token` missing or malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"406":{"$ref":"#/components/responses/EmailRevokeNotAllowed"},"429":{"$ref":"#/components/responses/Throttled"}}}}},"components":{"schemas":{"RevokeRequest":{"type":"object","required":["revoke_token"],"properties":{"revoke_token":{"type":"string","maxLength":1024,"description":"Signed token from the notice email/SMS, taken verbatim."}}},"ValidationErrorResponse":{"type":"object","description":"Standard DRF validation error response","additionalProperties":{"type":"array","items":{"type":"string"}}},"CodedErrorResponse":{"type":"object","description":"Business-error payload, returned with HTTP 406. `error_code` is stable —\nbranch on it, not on the translated message.","properties":{"non_field_errors":{"type":"string"},"error_code":{"type":"string"}}},"DetailErrorResponse":{"type":"object","properties":{"detail":{"type":"string"}}}},"responses":{"EmailRevokeNotAllowed":{"description":"The revoke token is invalid, expired, or has already been used. One code\ncovers all three — the response does not distinguish them.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodedErrorResponse"}}}},"Throttled":{"description":"Request was throttled (scope rate limit exceeded).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailErrorResponse"}}}}}}}
```

## Set Primary Email

> Sets a verified email as the primary email address. This is the link sent\
> to the new address by \`POST /users/email-change/\` — a real backend URL\
> taken from an email, not a client-generated one. If you route it through a\
> frontend page, forward the path segments unchanged.\
> \
> Unauthenticated: it may be opened in any browser.\
> \
> \*\*When \`EMAIL\_SET\_PRIMARY\_VIEW\` routes this to\
> \`omnishop.users.views.SecureEmailChangeSetPrimaryView\`\*\* it additionally:\
> \
> \- records an audit event carrying a single-use revoke token;\
> \- notifies the OLD address with a one-click revoke link\
> &#x20; (\`/users/email-change/revoke/\`), so a change the user did not make can be\
> &#x20; undone from the channel that was taken away.\
> \
> Completing a change the user asked for costs them nothing else: their\
> password, sessions and DRF auth token all keep working. The password\
> lockout belongs to \*\*revoke\*\* only.\
> \
> Re-visiting a still-valid link is an idempotent no-op: it returns \`200\`\
> without switching the address again, duplicating the notice, or re-running\
> the kill-switch.\
> \
> Throttling scope: \`email-set-primary\`.

```json
{"openapi":"3.1.0","info":{"title":"User API","version":"1.0.0"},"tags":[{"name":"Email","description":"Email management endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[],"paths":{"/users/email-set-primary/{signed_email}/{user_id_key}/":{"get":{"tags":["Email"],"summary":"Set Primary Email","description":"Sets a verified email as the primary email address. This is the link sent\nto the new address by `POST /users/email-change/` — a real backend URL\ntaken from an email, not a client-generated one. If you route it through a\nfrontend page, forward the path segments unchanged.\n\nUnauthenticated: it may be opened in any browser.\n\n**When `EMAIL_SET_PRIMARY_VIEW` routes this to\n`omnishop.users.views.SecureEmailChangeSetPrimaryView`** it additionally:\n\n- records an audit event carrying a single-use revoke token;\n- notifies the OLD address with a one-click revoke link\n  (`/users/email-change/revoke/`), so a change the user did not make can be\n  undone from the channel that was taken away.\n\nCompleting a change the user asked for costs them nothing else: their\npassword, sessions and DRF auth token all keep working. The password\nlockout belongs to **revoke** only.\n\nRe-visiting a still-valid link is an idempotent no-op: it returns `200`\nwithout switching the address again, duplicating the notice, or re-running\nthe kill-switch.\n\nThrottling scope: `email-set-primary`.","operationId":"setPrimaryEmail","parameters":[{"name":"signed_email","in":"path","required":true,"schema":{"type":"string"},"description":"Signed email string"},{"name":"user_id_key","in":"path","required":true,"schema":{"type":"string"},"description":"Signed user ID key"}],"responses":{"200":{"description":"Email set as primary"},"400":{"description":"Invalid signature or error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleErrorResponse"}}}},"429":{"$ref":"#/components/responses/Throttled"}}}}},"components":{"schemas":{"SimpleErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}},"DetailErrorResponse":{"type":"object","properties":{"detail":{"type":"string"}}}},"responses":{"Throttled":{"description":"Request was throttled (scope rate limit exceeded).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailErrorResponse"}}}}}}}
```

## Verify Email

> Verifies a user's email address via a signed link.\
> \
> \*\*Business Logic:\*\*\
> \- \*\*Verification:\*\* Validates the signed email and user ID.\
> \- \*\*Next Step:\*\* Upon successful verification, it \*\*triggers a notification\*\* (Email and SMS) containing the link to set this email as primary.\
> \- \*\*URL Format:\*\* The new notification contains a signed URL pointing to \`/users/email-set-primary/{signed\_email}/{user\_id\_key}/\`.

```json
{"openapi":"3.1.0","info":{"title":"User API","version":"1.0.0"},"tags":[{"name":"Email","description":"Email management endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[],"paths":{"/users/email-verify/{signed_email}/{user_id_key}":{"get":{"tags":["Email"],"summary":"Verify Email","description":"Verifies a user's email address via a signed link.\n\n**Business Logic:**\n- **Verification:** Validates the signed email and user ID.\n- **Next Step:** Upon successful verification, it **triggers a notification** (Email and SMS) containing the link to set this email as primary.\n- **URL Format:** The new notification contains a signed URL pointing to `/users/email-set-primary/{signed_email}/{user_id_key}/`.","operationId":"verifyEmail","parameters":[{"name":"signed_email","in":"path","required":true,"schema":{"type":"string"},"description":"Signed email string"},{"name":"user_id_key","in":"path","required":true,"schema":{"type":"string"},"description":"Signed user ID key"}],"responses":{"200":{"description":"Email verified"},"400":{"description":"Invalid signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleErrorResponse"}}}}}}}},"components":{"schemas":{"SimpleErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}}}}}
```

## Get User Emails

> Retrieves the user's primary email address.

```json
{"openapi":"3.1.0","info":{"title":"User API","version":"1.0.0"},"tags":[{"name":"Email","description":"Email management endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[{"cookieAuth":[]}],"components":{"securitySchemes":{"cookieAuth":{"type":"apiKey","in":"cookie","name":"sessionid"}},"schemas":{"UserEmail":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the email address. Read-only."},"user":{"type":"integer","description":"Identifier of the owning user. Ignored on input — the endpoint always uses the authenticated user. Read-only."},"email":{"type":"string","format":"email","description":"The email address. Required when adding a new email."},"verified":{"type":"boolean","description":"Indicates if the email address has been verified. Read-only."},"primary":{"type":"boolean","description":"Indicates if this is the primary email address for the user. Read-only."}}}}},"paths":{"/users/emails/":{"get":{"tags":["Email"],"summary":"Get User Emails","description":"Retrieves the user's primary email address.","operationId":"getUserEmails","responses":{"200":{"description":"Primary email details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserEmail"}}}}}}}}}
```

## Add Email Address

> Adds a new email address to the user's account.\
> \
> \*\*Business Logic:\*\*\
> \- \*\*Notifications:\*\*\
> &#x20; \- Sends a \*\*verification email\*\* to the new email address.\
> &#x20; \- Sends a \*\*verification SMS\*\* to the user's registered phone number.\
> \-         \*\*URL Format:\*\* The notifications contain a signed URL pointing to the \`/users/email-verify/{signed\_email}/{user\_id\_key}\` endpoint.\
> \
> \*\*Dynamic Settings:\*\*\
> \- \`NO\_REPLY\_EMAIL\`: Sender address for the email.

```json
{"openapi":"3.1.0","info":{"title":"User API","version":"1.0.0"},"tags":[{"name":"Email","description":"Email management endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[{"cookieAuth":[]}],"components":{"securitySchemes":{"cookieAuth":{"type":"apiKey","in":"cookie","name":"sessionid"}},"parameters":{"CSRFTokenHeader":{"name":"X-CSRFToken","in":"header","description":"CSRF token for write operations (POST, PUT, PATCH, DELETE).\nRequired for security when using session authentication.\nObtain token from cookie 'csrftoken' or meta tag in HTML.","required":true,"schema":{"type":"string"}},"CookieHeader":{"name":"Cookie","in":"header","description":"Session ID and CSRF token cookies.\nFormat: `sessionid=<id>; osessionid=<id>; csrftoken=<token>`","required":true,"schema":{"type":"string"}}},"schemas":{"UserEmail":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the email address. Read-only."},"user":{"type":"integer","description":"Identifier of the owning user. Ignored on input — the endpoint always uses the authenticated user. Read-only."},"email":{"type":"string","format":"email","description":"The email address. Required when adding a new email."},"verified":{"type":"boolean","description":"Indicates if the email address has been verified. Read-only."},"primary":{"type":"boolean","description":"Indicates if this is the primary email address for the user. Read-only."}}},"ValidationErrorResponse":{"type":"object","description":"Standard DRF validation error response","additionalProperties":{"type":"array","items":{"type":"string"}}}}},"paths":{"/users/emails/":{"post":{"tags":["Email"],"summary":"Add Email Address","description":"Adds a new email address to the user's account.\n\n**Business Logic:**\n- **Notifications:**\n  - Sends a **verification email** to the new email address.\n  - Sends a **verification SMS** to the user's registered phone number.\n-         **URL Format:** The notifications contain a signed URL pointing to the `/users/email-verify/{signed_email}/{user_id_key}` endpoint.\n\n**Dynamic Settings:**\n- `NO_REPLY_EMAIL`: Sender address for the email.","operationId":"addEmailAddress","parameters":[{"$ref":"#/components/parameters/CSRFTokenHeader"},{"$ref":"#/components/parameters/CookieHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserEmail"}}}},"responses":{"200":{"description":"Email added successfully"},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}}}}}}}
```

## List All User Emails

> Lists every email address of the user, primary or not.\
> \
> \*\*Business Logic:\*\*\
> \- An email change does not delete the previous address; it only unsets\
> &#x20; the \`primary\` flag and keeps the record. Those addresses are reachable\
> &#x20; here alone, since \`GET /users/emails/\` returns the primary one by\
> &#x20; itself.\
> \- Scoped to the authenticated user, and ordered with the primary address\
> &#x20; first, the remaining ones from oldest to newest.\
> \
> \*\*Notes:\*\*\
> \- Unverified addresses are listed as well, so read \`verified\` per item\
> &#x20; instead of assuming every listed address is confirmed.\
> \- The response is a plain array: no pagination, no filtering.

```json
{"openapi":"3.1.0","info":{"title":"User API","version":"1.0.0"},"tags":[{"name":"Email","description":"Email management endpoints"}],"servers":[{"description":"Server base URL","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[{"cookieAuth":[]}],"components":{"securitySchemes":{"cookieAuth":{"type":"apiKey","in":"cookie","name":"sessionid"}},"schemas":{"UserEmail":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the email address. Read-only."},"user":{"type":"integer","description":"Identifier of the owning user. Ignored on input — the endpoint always uses the authenticated user. Read-only."},"email":{"type":"string","format":"email","description":"The email address. Required when adding a new email."},"verified":{"type":"boolean","description":"Indicates if the email address has been verified. Read-only."},"primary":{"type":"boolean","description":"Indicates if this is the primary email address for the user. Read-only."}}},"DetailErrorResponse":{"type":"object","properties":{"detail":{"type":"string"}}}},"responses":{"UnauthorizedError":{"description":"Authentication credentials were not provided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailErrorResponse"}}}}}},"paths":{"/users/emails/all/":{"get":{"tags":["Email"],"summary":"List All User Emails","description":"Lists every email address of the user, primary or not.\n\n**Business Logic:**\n- An email change does not delete the previous address; it only unsets\n  the `primary` flag and keeps the record. Those addresses are reachable\n  here alone, since `GET /users/emails/` returns the primary one by\n  itself.\n- Scoped to the authenticated user, and ordered with the primary address\n  first, the remaining ones from oldest to newest.\n\n**Notes:**\n- Unverified addresses are listed as well, so read `verified` per item\n  instead of assuming every listed address is confirmed.\n- The response is a plain array: no pagination, no filtering.","operationId":"listAllUserEmails","responses":{"200":{"description":"All email addresses of the user","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/UserEmail"}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://apidocs.akinon.com/commerce-openapis/users/module-2/email.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
