Email Address Management

The Email Management API allows users to update and verify their email addresses. This API provides secure email change functionality with proper verification steps.

Overview

Email management features include:

• Email address verification

• Email address change with verification

• Email verification status checking

• Resending verification emails

Endpoints

Change Email Address

POST /api/v1/users/{userId}/email/change

Verify Email Address

POST /api/v1/users/{userId}/email/verify

Check Email Status

GET /api/v1/users/{userId}/email/status

Resend Verification

POST /api/v1/users/{userId}/email/resend-verification

Authentication

All email management endpoints require user authentication:

Authorization: Bearer YOUR_ACCESS_TOKEN
X-Required-Scope: email:manage

Change Email Address

Request

{
  "new_email": "[e-mail]",
  "current_password": "user_current_password",
  "verification_method": "email_link"
}

Parameters

Parameter	Type	Required	Description
new_email	string	Yes	New email address (valid email format)
current_password	string	Yes	User's current password for verification
verification_method	string	No	Verification method: email_link or email_code

Response

{
  "success": true,
  "data": {
    "change_request_id": "ecr_1234567890",
    "status": "pending_verification",
    "new_email": "[e-mail]",
    "verification_method": "email_link",
    "verification_expires_at": "2025-07-11T22:30:00Z",
    "current_email_retained": true
  },
  "message": "Email change initiated. Please verify your new email address.",
  "timestamp": "2025-07-11T10:30:00Z"
}

Verify Email Address

Request

{
  "verification_code": "123456",
  "change_request_id": "ecr_1234567890"
}

Parameters

Parameter	Type	Required	Description
verification_code	string	Yes	6-digit verification code
change_request_id	string	Yes	Email change request ID

Response

{
  "success": true,
  "data": {
    "email_verified": true,
    "new_email": "[e-mail]",
    "changed_at": "2025-07-11T10:35:00Z",
    "notification_sent": true
  },
  "message": "Email address updated successfully",
  "timestamp": "2025-07-11T10:35:00Z"
}

Check Email Status

Response

{
  "success": true,
  "data": {
    "current_email": "[e-mail]",
    "email_verified": true,
    "verified_at": "2025-01-15T08:00:00Z",
    "pending_change": {
      "has_pending": true,
      "new_email": "[e-mail]",
      "requested_at": "2025-07-11T10:30:00Z",
      "expires_at": "2025-07-11T22:30:00Z"
    }
  },
  "timestamp": "2025-07-11T10:30:00Z"
}

Resend Verification

Request

{
  "change_request_id": "ecr_1234567890",
  "verification_method": "email_code"
}

Response

{
  "success": true,
  "data": {
    "verification_sent": true,
    "method": "email_code",
    "expires_at": "2025-07-11T22:30:00Z",
    "resend_available_at": "2025-07-11T10:35:00Z"
  },
  "message": "Verification code resent successfully",
  "timestamp": "2025-07-11T10:30:00Z"
}

Email Change Process

The email change process follows these steps:

1. Initiate Change: User provides new email and current password

2. Send Verification: System sends verification to new email

3. Verify Email: User confirms via code or link

4. Complete Change: Email is updated and notifications sent

5. Security Alert: Original email receives change notification

Verification Methods

Email Link

• One-click verification via secure link

• Link expires in 12 hours

• More user-friendly but requires email client support

Email Code

• 6-digit numeric code

• Code expires in 12 hours

• More reliable across all email clients

Security Features

Password Verification

Email changes require current password verification to prevent unauthorized changes.

Rate Limiting

• Email change requests: 3 per hour

• Verification attempts: 5 per request

• Resend verification: 1 per 5 minutes

Notification System

• Original email receives change notification

• Security alerts for suspicious activity

• Account recovery options provided

Error Codes

Code	Description
EMAIL_001	Invalid email format
EMAIL_002	Email already in use
EMAIL_003	Invalid verification code
EMAIL_004	Verification expired
EMAIL_005	Too many verification attempts
EMAIL_006	Invalid change request ID
EMAIL_007	Password verification failed
EMAIL_008	Rate limit exceeded
EMAIL_009	Email service unavailable

Best Practices

1. Email Validation: Validate email format before API calls

2. User Experience: Provide clear instructions for verification

3. Security: Always verify current password for email changes

4. Notifications: Inform users about email change process

5. Fallback: Provide alternative verification methods

6. Timeout Handling: Handle verification timeouts gracefully

Integration Examples

JavaScript/Node.js

const upbond = require('@upbond/user-management-js');

async function changeEmail(userId, newEmail, currentPassword, accessToken) {
  try {
    // Initiate email change
    const changeResponse = await upbond.users.email.change(userId, {
      new_email: newEmail,
      current_password: currentPassword,
      verification_method: 'email_code'
    }, {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    });

    console.log('Email change initiated:', changeResponse.data.change_request_id);
    
    // User receives email with verification code
    const verificationCode = await getUserInput('Enter verification code: ');
    
    // Verify email change
    const verifyResponse = await upbond.users.email.verify(userId, {
      verification_code: verificationCode,
      change_request_id: changeResponse.data.change_request_id
    }, {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    });

    console.log('Email changed successfully:', verifyResponse.data.new_email);
    return verifyResponse.data;
  } catch (error) {
    console.error('Email change failed:', error.response.data);
    throw error;
  }
}

Python

import upbond_user_management as upbond

def change_email(user_id, new_email, current_password, access_token):
    try:
        # Initiate email change
        change_response = upbond.users.email.change(
            user_id=user_id,
            new_email=new_email,
            current_password=current_password,
            verification_method="email_code",
            headers={"Authorization": f"Bearer {access_token}"}
        )
        
        print(f"Email change initiated: {change_response['data']['change_request_id']}")
        
        # User receives email with verification code
        verification_code = input("Enter verification code: ")
        
        # Verify email change
        verify_response = upbond.users.email.verify(
            user_id=user_id,
            verification_code=verification_code,
            change_request_id=change_response['data']['change_request_id'],
            headers={"Authorization": f"Bearer {access_token}"}
        )
        
        print(f"Email changed successfully: {verify_response['data']['new_email']}")
        return verify_response['data']
    except Exception as error:
        print(f"Email change failed: {error}")
        raise

Email Templates

The system sends the following email templates:

Verification Email

Subject: Verify Your New Email Address

Hi [USER_NAME],

You recently requested to change your email address. Please verify your new email address by clicking the link below or entering the verification code.

Verification Code: [CODE]
Verification Link: [LINK]

This code will expire in 12 hours.

If you didn't request this change, please contact support immediately.

Best regards,
UPBOND Team

Change Confirmation Email

Subject: Email Address Changed

Hi [USER_NAME],

Your email address has been successfully changed from [OLD_EMAIL] to [NEW_EMAIL].

Changed on: [DATE]
IP Address: [IP]

If you didn't make this change, please contact support immediately.

Best regards,
UPBOND Team

Support

For email management issues:

• Technical Support: [e-mail]

• Account Security: [e-mail]

• Email Delivery Issues: [e-mail]