Email Management API Endpoints

Relevant source files

The following files were used as context for generating this wiki page:

• backend/server.py
• frontend/src/App.js
• backend_test.py
• test_result.md
• frontend/src/App.css

Introduction

The Email Management API is a core module within the NEXUS Digital Account & Trial Tracking System. It provides a robust set of RESTful endpoints designed to manage user-specific email addresses, which serve as primary identifiers for tracking digital accounts and free trials. The system allows users to categorize emails by purpose (e.g., Personal, Work, Trials), monitor security status, and designate primary contact addresses.

The API is built using FastAPI and integrates with MongoDB (via Motor) for persistent storage. Access to these endpoints is strictly controlled via JWT-based authentication, ensuring that users can only interact with email records associated with their unique user_id.

Architecture and Authentication

The Email Management module follows a protected resource pattern. Every request to the /api/emails endpoints must include a valid JSON Web Token (JWT) in the Authorization header.

Authentication Flow

The backend utilizes the verify_token dependency to extract the username from the JWT payload and get_current_user to retrieve the user's document from the database. This ensures data isolation between different users.

Data Models and Enums

The system uses Pydantic models to enforce strict data validation for incoming requests and outgoing responses.

Email Schema

Field	Type	Description
id	String (UUID)	Unique identifier for the email record.
user_id	String	Reference to the owner's User ID.
email_address	EmailStr	The validated email address.
provider	String	Email service provider (e.g., Gmail, Outlook).
purpose	EmailPurpose	Enum: PERSONAL, WORK, TRIALS, SHOPPING, THROWAWAY.
is_primary	Boolean	Flag indicating the primary email for the user.
security_status	SecurityStatus	Enum: SECURE, COMPROMISED, UNKNOWN.
notes	String (Optional)	User-defined notes about the email account.

Sources: backend/server.py:84-106, backend/server.py:114-124

Functional Enums

The API utilizes Python Enums to maintain data integrity across the platform:

• EmailPurpose: Categorizes the usage of the email (e.g., TRIALS is specifically for account sign-ups).
• SecurityStatus: Tracks the health of the email account (e.g., COMPROMISED triggers alerts).

Sources: backend/server.py:68-79

API Endpoints Summary

Endpoint Definition

Method	Endpoint	Description
POST	/api/emails	Create a new email record.
GET	/api/emails	Retrieve all emails for the authenticated user.
GET	/api/emails/{id}	Retrieve details of a specific email.
PUT	/api/emails/{id}	Update an existing email record.
DELETE	/api/emails/{id}	Permanently remove an email record.

Sources: backend/server.py:202-238

Create Email (POST)

When creating a new email, the backend automatically assigns the user_id from the authenticated session and generates a unique UUID.

@api_router.post("/emails", response_model=Email)
async def create_email(email: EmailCreate, current_user: User = Depends(get_current_user)):
    email_dict = email.dict()
    email_dict['user_id'] = current_user.id
    new_email = Email(**email_dict)
    await db.emails.insert_one(new_email.dict())
    return new_email

Sources: backend/server.py:202-208

Email Retrieval and Isolation (GET)

The API implements a query filter {"user_id": current_user.id} on all retrieval operations to prevent unauthorized access to other users' data (IDOR prevention).

Frontend Integration

The frontend interacts with these endpoints using axios. In the Emails component, the system fetches and displays emails as glassmorphic cards with color-coded badges based on the purpose and security_status.

Frontend Logic Example

The fetchEmails function in App.js demonstrates the consumption of the GET endpoint:

const fetchEmails = async () => {
  try {
    const response = await axios.get(`${API}/emails`);
    setEmails(response.data);
  } catch (error) {
    console.error('Error fetching emails:', error);
  }
};

Sources: frontend/src/App.js:591-599, frontend/src/App.css:550-580

Testing and Validation

The Email API has been verified through a Python-based testing suite (backend_test.py) and a comprehensive testing protocol.

Verified Test Cases

• Creation: Successfully creates emails with provider and purpose fields.
• Isolation: Ensures User A cannot see User B's emails.
• Updates: Verifies that security status updates are reflected in the database.
• Deletion: Confirms 404 responses for deleted resource lookups.

Sources: backend_test.py:108-196, test_result.md:111-114

Conclusion

The Email Management API Endpoints provide a secure and structured way to handle the foundational identity layer of the NEXUS system. By combining FastAPI's validation, JWT security, and strict database-level user isolation, the module ensures that sensitive email data remains protected while remaining easily accessible for account and trial tracking functionalities.