# 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=; osessionid=; csrftoken=`","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:\*\*\ > \- Sends a \*\*verification email\*\* to the new email address.\ > \- 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=; osessionid=; csrftoken=`","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"}}}}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://apidocs.akinon.com/commerce-openapis/users/module-2/email.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.