Adding a Homeowner Customer

Overview

Homeowner customers are your bread and butter for residential contracting. Adding them to BlueClerk lets you create tickets, schedule jobs, send invoices, and maintain a complete work history at their properties. The new smart customer input makes adding homeowners faster - just start typing a name and BlueClerk searches existing records, suggests matches, and lets you create new customers with Google Places address autocomplete.

NEW: Disposable Email Protection - BlueClerk now blocks throwaway email addresses (yopmail, mailinator, tempmail, etc.) when creating homeowner customers in production. This prevents fake customer records and keeps your database clean. A yellow "NEEDS REVIEW" badge appears next to any existing customers with disposable emails so you can verify their legitimacy.

Quick Add with Smart Customer Input

How It Works

1. Go to Customers in the main navigation
2. Click "Add Customer" or the + button
3. Start typing a name or address in the search box
4. BlueClerk searches automatically across:
   • Existing homeowners in your company
   • Shared homeowner records from other contractors
5. Select a match to reuse an existing customer, or create new if no match found
6. Fill in the details:
   • Name (required)
   • Email (required) - Must be a real email address, not a disposable/throwaway domain
   • Phone (optional but recommended)
   • Address - Uses Google Places autocomplete for accuracy
   • Subdivision (optional) - If the home is in a builder's subdivision
   • Lot number (optional)

Email Address Requirements

Blocked Disposable Domains

BlueClerk rejects email addresses from known disposable/throwaway providers including:

• yopmail.com
• mailinator.com
• tempmail.com
• guerrillamail.com
• 10minutemail.com
• And ~25 other throwaway email services

Why This Matters

Real customers don't use disposable email addresses. Blocking these domains:

• Prevents fake customer records from cluttering your database
• Protects data quality for shared customer records
• Ensures reliable communication - throwaway emails expire quickly
• Maintains audit trails - real emails help with accountability

Development & Testing

For developers and QA:

• Production only - The block only applies in production environments
• Development bypass - Set ALLOW_DISPOSABLE_EMAILS=1 in your .env to allow disposables in local/test environments
• Seed scripts work - Test fixtures using yopmail continue to function in non-production

Identifying Customers with Disposable Emails

NEEDS REVIEW Badge

In the customer list, you'll see a yellow "NEEDS REVIEW" badge with a warning icon next to any customer whose email domain is on the disposable list:

• Hover over the badge to see: "Disposable / throwaway email — review whether this customer is real"
• These customers may be fake - review them and update with real contact information
• Badge covers legacy data - Shows on customers created before the guard was added

What to Do

When you see a NEEDS REVIEW badge:

1. Contact the customer using their phone number if available
2. Request a real email address for invoicing and communication
3. Update the customer record with the verified email
4. Consider deleting if the customer was created in error or is clearly fake

Audit Trail

Every customer creation is now logged automatically:

• Who created it - User ID and email of the person who added the customer
• When it was created - Timestamp of creation
• Customer details - Type (homeowner/builder/business), name, email, and source
• Searchable history - Admins can review the audit log for forensics

This helps with:

• Accountability - Know who added which customers
• Quality control - Identify patterns of fake customer creation
• Dispute resolution - Historical record of customer additions
• Compliance - Meet audit requirements for customer data

Adding Properties

When creating a homeowner:

1. Enter their address using Google Places autocomplete
2. BlueClerk checks for duplicates - Prevents creating duplicate property records
3. If the address exists, the customer is linked to the existing property
4. If new, a property record is created automatically with:
   • Full address and location coordinates
   • Google Maps placeId for accuracy
   • Link to the homeowner customer

Tips

• Use real email addresses - Required for invoicing, payment reminders, and communication
• Add phone numbers - Makes scheduling and follow-up much easier
• Include subdivision details - Helps organize builder warranty work
• Verify contact information - Double-check email and phone before saving
• Review flagged customers - Check any customer with a NEEDS REVIEW badge

Questions

Q: What happens if I try to use a disposable email? A: You'll see an error message: "Disposable / throwaway email addresses (yopmail, mailinator, tempmail, etc.) cannot be used for customer records." You'll need to use a real email address to proceed.

Q: Why do some existing customers have the NEEDS REVIEW badge? A: These customers were created before the disposable email guard was added, or were imported from external sources. Review them and update their contact information with real email addresses.

Q: Can I still create customers with disposable emails in my test environment? A: Yes - the block only applies in production. Development and test environments allow disposable emails so seed scripts and test fixtures continue to work.

Q: What if I need to create a customer without an email? A: The email field is required for homeowners because it's essential for invoicing and communication. If the customer truly has no email, consider collecting one before adding them to BlueClerk.

Q: Will the audit log slow down customer creation? A: No - audit logging is fire-and-forget. It runs asynchronously and never blocks the main request, so customer creation remains fast.