# 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."},"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:\*\*\
>   \- Sends a \*\*confirmation email\*\* to the new email address.\
>   \- 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\*\*.

```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":{"UserEmailChangeRequest":{"type":"object","required":["user","email","password"],"properties":{"user":{"type":"integer","description":"User ID."},"email":{"type":"string","format":"email","description":"The new email address. Must be different from the current email and not already in use."},"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"}}}}},"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**.","operationId":"requestEmailChange","parameters":[{"$ref":"#/components/parameters/CSRFTokenHeader"},{"$ref":"#/components/parameters/CookieHeader"}],"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"}}}}}}}}}
```

## Set Primary Email

> Sets a verified email as the 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":[],"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.","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"}}}}}}}},"components":{"schemas":{"SimpleErrorResponse":{"type":"object","properties":{"error":{"type":"string"}}}}}}
```

## 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."},"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."},"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"}}}}}}}}}
```