================================================================================
DETAILED INSTALLATION GUIDE - LEGALLYMAIL FOR SALESFORCE
================================================================================

This document provides step-by-step instructions for installing and configuring
the LegallyMail Certified Email component in your Salesforce organization.

================================================================================
TABLE OF CONTENTS
================================================================================
1. Prerequisites
2. Environment Preparation
3. Package Download
4. Installation via Salesforce CLI
5. Post-Installation Configuration
6. User Interface Configuration
7. Installation Verification
8. Common Troubleshooting

================================================================================
1. PREREQUISITES
================================================================================

Before starting the installation, make sure you have:

1.1. A Salesforce Organization
   - Salesforce Developer Edition (recommended for testing)
   - Salesforce Enterprise, Unlimited, or Performance Edition
   - You can register for free at: https://developer.salesforce.com/signup

1.2. Salesforce CLI Installed
   - Download from: https://developer.salesforce.com/tools/sfdxcli
   - Minimum required version: 2.0.0 or higher
   - To verify installation, run in terminal:
     sf --version

1.3. LegallyMail Account
   - Register at: https://legallymail.com
   - Get your API Token from the dashboard
   - The token is located at: Settings > API > Access Token

1.4. User Permissions
   - You must have "System Administrator" profile in Salesforce
   - Or permissions to:
     * Modify All Data
     * Customize Application
     * Manage Users

================================================================================
2. ENVIRONMENT PREPARATION
================================================================================

2.1. Verify Salesforce CLI
   Open a terminal or command prompt and run:
   
   sf --version
   
   You should see something like:
   @salesforce/cli/2.x.x

2.2. Verify Internet Connection
   The installation process requires a stable internet connection for:
   - Salesforce authentication
   - Dependency downloads
   - Component deployment

2.3. Prepare Credentials
   Have ready:
   - Your Salesforce organization username and password
   - Your LegallyMail API Token

================================================================================
3. PACKAGE DOWNLOAD
================================================================================

3.1. Download the Package
   - Visit: https://legallymail.com/download-plugins
   - Locate the Salesforce plugin
   - Download the file: sfdx-project.zip
   - Approximate size: 50-100 KB

3.2. Extract the File
   - Unzip sfdx-project.zip to a location of your choice
   - Example on Windows: C:\LegallyMail\salesforce_app
   - Example on Mac/Linux: ~/LegallyMail/salesforce_app
   
   The folder structure should look like this:
   salesforce_app/
   ├── force-app/
   │   └── main/
   │       └── default/
   │           ├── classes/
   │           ├── lwc/
   │           ├── objects/
   │           └── tabs/
   ├── sfdx-project.json
   └── README.md

================================================================================
4. INSTALLATION VIA SALESFORCE CLI
================================================================================

4.1. Open Terminal in Project Directory
   - Windows: Open PowerShell or CMD
   - Mac/Linux: Open Terminal
   - Navigate to the extracted directory:
     
     cd C:\LegallyMail\salesforce_app
     
     Or on Mac/Linux:
     
     cd ~/LegallyMail/salesforce_app

4.2. Authenticate to Salesforce
   Run the following command:
   
   sf org login web --set-default
   
   This will open a browser window:
   - Enter your Salesforce username and password
   - Click "Allow" when authorization is requested
   - The terminal will show: "Successfully authorized [your-username]"
   
   NOTE: If you already have an active session, you can use:
   sf org login web --alias legallymail-org

4.3. Verify Connection
   Run:
   
   sf org display
   
   You should see your organization information:
   - Org ID
   - Username
   - Instance URL
   - Access Token (partially hidden)

4.4. Deploy Source Code
   Run the deployment command:
   
   sf project deploy start
   
   The process may take 1-3 minutes. You'll see output similar to:
   
   Deploying v58.0 metadata to [your-org]...
   ✓ Preparing deployment
   ✓ Deploying metadata
   ✓ Running tests
   
   Deploy Succeeded.
   
   IMPORTANT: If you see errors, consult section 8 (Troubleshooting).

4.5. Verify Deployment
   Run:
   
   sf project deploy report
   
   This will show a summary of deployed components:
   - ApexClass: LegallyMailService, LegallyMailController
   - CustomObject: LegallyMail_Log__c, LegallyMail_Template__c
   - LightningComponentBundle: legallyMailSender, legallyMailBulkSend
   - CustomTab: LegallyMail_Logs, LegallyMail_Templates

================================================================================
5. POST-INSTALLATION CONFIGURATION
================================================================================

Once the code is deployed, you need to configure some settings in Salesforce:

5.1. CONFIGURE REMOTE SITE SETTINGS
   
   Salesforce requires explicit authorization to connect to external APIs.
   
   Step 1: Access Setup
   - Log in to your Salesforce organization
   - Click the gear icon (⚙️) in the upper right corner
   - Select "Setup"
   
   Step 2: Search for Remote Site Settings
   - In the Quick Find search box, type: "Remote Site"
   - Click "Remote Site Settings"
   
   Step 3: Create New Remote Site
   - Click the "New Remote Site" button
   - Fill in the fields:
     * Remote Site Name: LegallyMailAPI
     * Remote Site URL: https://legallymail.com
     * Description: API endpoint for LegallyMail certified email service
     * Active: ✓ (checked)
   - Click "Save"
   
   NOTE: Without this step, API calls will fail with unauthorized endpoint error.

5.2. CONFIGURE API TOKEN
   
   You must provide your LegallyMail API token to the code.
   
   OPTION A: Quick Setup (For Development/Testing)
   
   Step 1: Access Apex Classes
   - In Setup, search for "Apex Classes" in Quick Find
   - Click "Apex Classes"
   
   Step 2: Edit LegallyMailService
   - Locate the "LegallyMailService" class in the list
   - Click "Edit" next to it
   
   Step 3: Update the Token
   - Find the getApiToken() method:
     
     private static String getApiToken() {
         return 'YOUR_API_TOKEN';
     }
   
   - Replace 'YOUR_API_TOKEN' with your actual LegallyMail token
   - Example:
     
     private static String getApiToken() {
         return 'lm_live_abc123xyz789def456ghi012jkl345';
     }
   
   - Click "Save"
   
   OPTION B: Secure Setup (For Production) - RECOMMENDED
   
   Step 1: Create Custom Metadata Type
   - In Setup, search for "Custom Metadata Types"
   - Create a new type called "LegallyMail_Settings"
   - Add a text field: "API_Token__c"
   
   Step 2: Create Record
   - Create a new record with your API Token
   - Label: Default
   - API Token: [your-token-here]
   
   Step 3: Update the Code
   - Modify the getApiToken() method to read from Custom Metadata:
     
     private static String getApiToken() {
         LegallyMail_Settings__mdt settings = 
             LegallyMail_Settings__mdt.getInstance('Default');
         return settings.API_Token__c;
     }
   
   ADVANTAGE: The token is not hardcoded and can be changed without modifying code.

5.3. CONFIGURE CUSTOM OBJECT PERMISSIONS
   
   Step 1: Access Permission Sets or Profiles
   - In Setup, search for "Permission Sets" or "Profiles"
   
   Step 2: Edit Permissions
   - Select the "System Administrator" profile or create a Permission Set
   - Go to "Object Settings"
   - Search for:
     * LegallyMail Log
     * LegallyMail Template
   
   Step 3: Enable Permissions
   - For each object, enable:
     ✓ Read
     ✓ Create
     ✓ Edit
     ✓ Delete
     ✓ View All
     ✓ Modify All
   
   - Click "Save"

================================================================================
6. USER INTERFACE CONFIGURATION
================================================================================

6.1. ADD COMPONENT TO RECORD PAGES
   
   To send certified emails from individual records:
   
   Step 1: Navigate to a Contact Record
   - Go to the "Contacts" tab
   - Open any existing contact or create a new one
   
   Step 2: Edit the Page
   - Click the gear icon (⚙️) in the upper right corner
   - Select "Edit Page"
   - The Lightning App Builder will open
   
   Step 3: Add the Component
   - In the left panel, search for "Custom"
   - Locate the component: "legallyMailSender"
   - Drag and drop the component onto the page
   - Recommended location: Right column, below contact details
   
   Step 4: Configure the Component (Optional)
   - Select the component on the page
   - In the right panel, you can adjust:
     * Component height
     * Conditional visibility
   
   Step 5: Save and Activate
   - Click "Save"
   - Click "Activate"
   - Select "Assign as Org Default"
   - Check the options:
     ✓ Desktop
     ✓ Phone
     ✓ Tablet
   - Click "Next" then "Save"
   
   Step 6: Repeat for Leads
   - Repeat steps 1-5 for Lead record pages
   - You can also add it to Account pages if desired

6.2. ENABLE BULK SENDING
   
   To send certified emails to multiple contacts at once:
   
   Step 1: Access Object Manager
   - In Setup, search for "Object Manager"
   - Click "Object Manager"
   
   Step 2: Select Contact
   - In the object list, search for and click "Contact"
   
   Step 3: Create New Action
   - In the left sidebar, click "Buttons, Links, and Actions"
   - Click "New Action"
   
   Step 4: Configure the Action
   - Action Type: Lightning Web Component
   - Lightning Web Component: c:legallyMailBulkSend
   - Height: 600 (pixels)
   - Label: Send Certified Email (Bulk)
   - Name: Send_Certified_Email_Bulk
   - Description: Send certified emails to multiple contacts at once
   - Click "Save"
   
   Step 5: Add to List View
   - Go to "Search Layouts for Salesforce Classic"
   - Click "Edit" next to "List View"
   - Not necessary to add here for Lightning Experience
   
   Step 6: Add to Lightning List View
   - Exit Setup
   - Go to the "Contacts" tab
   - Click the gear icon next to any list view
   - Select "Select List Display"
   - In "Available Actions", search for "Send Certified Email (Bulk)"
   - Drag it to "Selected Actions"
   - Click "Save"
   
   Step 7: Repeat for Leads
   - Repeat steps 2-6 for the Lead object

6.3. CONFIGURE NAVIGATION TABS
   
   To easily access logs and templates:
   
   Step 1: Edit Navigation App
   - Click the App Launcher (9-dot icon) in the upper left corner
   - Click "Edit" next to "Sales" or the app you use
   
   Step 2: Add Tabs
   - In "Available Items", search for:
     * LegallyMail Logs
     * LegallyMail Templates
   - Drag them to "Selected Items"
   - Order them according to your preference
   
   Step 3: Save
   - Click "Save"
   
   Now you can access logs and templates from the main menu.

================================================================================
7. INSTALLATION VERIFICATION
================================================================================

7.1. Verify Deployed Components
   
   Step 1: Verify Apex Classes
   - In Setup, search for "Apex Classes"
   - Confirm that these exist:
     ✓ LegallyMailService
     ✓ LegallyMailController
   
   Step 2: Verify Lightning Web Components
   - In Setup, search for "Lightning Components"
   - Confirm that these exist:
     ✓ legallyMailSender
     ✓ legallyMailBulkSend
   
   Step 3: Verify Custom Objects
   - In Setup, search for "Object Manager"
   - Confirm that these exist:
     ✓ LegallyMail Log
     ✓ LegallyMail Template

7.2. Individual Sending Test
   
   Step 1: Create or Open a Contact
   - Make sure it has a valid email address
   
   Step 2: Use the Component
   - Locate the "LegallyMail Certified Email" component on the page
   - Verify that the contact's email loads automatically
   
   Step 3: Send Test Email
   - Subject: Test Email
   - Message: This is a test certified email from Salesforce
   - Click "Send Certified Email"
   
   Step 4: Verify Response
   - You should see a success message with a Tracking ID
   - Example: "Email sent successfully! Tracking ID: LM-2026-ABC123"
   
   Step 5: Verify Log
   - Go to the "LegallyMail Logs" tab
   - You should see the recently sent email
   - Verify it shows:
     * Recipient Email
     * Subject
     * Tracking ID
     * Status: Sent

7.3. Bulk Sending Test
   
   Step 1: Go to Contacts List
   - Go to the "Contacts" tab
   - Select any list view
   
   Step 2: Select Multiple Contacts
   - Check the boxes for 2-3 contacts with valid emails
   
   Step 3: Execute Bulk Action
   - Click the actions dropdown menu
   - Select "Send Certified Email (Bulk)"
   
   Step 4: Complete Form
   - Verify it shows the correct number of recipients
   - Subject: Bulk Test Email
   - Message: This is a bulk certified email test
   - Click "Send Bulk"
   
   Step 5: Verify Results
   - You should see a summary of successful sends
   - Check the logs to confirm all sends

7.4. Templates Test
   
   Step 1: Create Template
   - Go to "LegallyMail Templates"
   - Click "New"
   - Name: Welcome Email
   - Subject: Welcome to Our Service
   - Body: Dear Customer, welcome to our service...
   - Click "Save"
   
   Step 2: Use Template
   - Open a contact
   - In the LegallyMail component, select the template from the dropdown
   - Verify that Subject and Message are filled automatically
   
   Step 3: Send with Template
   - Click "Send Certified Email"
   - Verify it sends correctly

================================================================================
8. COMMON TROUBLESHOOTING
================================================================================

8.1. Error: "Remote host closed connection during handshake"
   
   CAUSE: Remote Site Settings not configured correctly
   
   SOLUTION:
   - Go to Setup > Remote Site Settings
   - Verify that "LegallyMailAPI" exists
   - Verify the URL is exactly: https://legallymail.com
   - Verify it's marked as "Active"
   - If it exists, delete it and create it again

8.2. Error: "Unauthorized endpoint"
   
   CAUSE: Incorrect or unconfigured API Token
   
   SOLUTION:
   - Go to Setup > Apex Classes > LegallyMailService
   - Verify the token is correct
   - Copy the token directly from your LegallyMail account
   - Make sure not to include spaces at the beginning or end
   - Verify the token hasn't expired

8.3. Error: "Component not found on page"
   
   CAUSE: Component not added to page or not activated
   
   SOLUTION:
   - Open a Contact or Lead record
   - Click ⚙️ > Edit Page
   - Verify the "legallyMailSender" component is on the page
   - If not, add it from the left panel
   - Click Save > Activate > Assign as Org Default

8.4. Error: "Bulk action doesn't appear"
   
   CAUSE: Action not added to List View
   
   SOLUTION:
   - Go to Setup > Object Manager > Contact
   - Click "Buttons, Links, and Actions"
   - Verify "Send_Certified_Email_Bulk" exists
   - If not, create it following section 6.2
   - Go to Contacts list view
   - Click ⚙️ > Select List Display
   - Add the action to "Selected Actions"

8.5. Error: "Deployment failed"
   
   CAUSE: Conflicts with existing components or insufficient permissions
   
   SOLUTION:
   - Verify you have administrator permissions
   - Run: sf org display
   - Confirm you're connected to the correct org
   - Try deploying again with verbose mode:
     sf project deploy start --verbose
   - Review specific error messages
   - If there are name conflicts, rename the components

8.6. Error: "Email not sent - API error"
   
   CAUSE: Issues with LegallyMail API or insufficient balance
   
   SOLUTION:
   - Verify your balance at legallymail.com
   - Verify your account is active
   - Review Salesforce logs:
     Setup > Debug Logs > New
     Reproduce the error
     Review the log to see the exact error message
   - Contact support: support@legallymail.com

8.7. Error: "Invalid email address"
   
   CAUSE: Record doesn't have a valid email
   
   SOLUTION:
   - Verify the Contact/Lead has an email in the "Email" field
   - Verify the format is valid (example@domain.com)
   - Update the email and try again

8.8. Component doesn't load email automatically
   
   CAUSE: Component not detecting record context
   
   SOLUTION:
   - Verify you're on a Contact or Lead page
   - Refresh the page (F5)
   - If it persists, edit the page and reposition the component
   - Check Developer Console for JavaScript errors:
     F12 > Console

================================================================================
9. ADDITIONAL INFORMATION
================================================================================

9.1. Salesforce Limits
   - API calls per day: Depends on your Salesforce edition
   - Developer Edition: 15,000 calls/day
   - Enterprise Edition: 100,000 calls/day
   - Each certified email consumes 1 API call

9.2. LegallyMail Limits
   - Maximum attachment size: 10 MB per file
   - Maximum number of attachments: 4 per email
   - Supported formats: PDF, DOC, DOCX, JPG, PNG
   - Maximum message length: 50,000 characters

9.3. Best Practices
   - Use templates for recurring emails
   - Review logs regularly to monitor status
   - Configure Named Credentials in production (don't hardcode token)
   - Backup your templates periodically
   - Train users before giving mass access

9.4. Updates
   - Check for updates at: https://legallymail.com/download-plugins
   - To update, simply run:
     sf project deploy start
   - Existing data (logs, templates) will be preserved

9.5. Uninstallation
   If you need to uninstall the component:
   
   Step 1: Remove from Pages
   - Remove the component from all record pages
   
   Step 2: Delete Actions
   - Delete bulk actions from Contact and Lead
   
   Step 3: Delete Components
   - In Setup > Apex Classes, delete the classes
   - In Setup > Lightning Components, delete the components
   
   Step 4: Delete Objects (CAUTION: This will delete all data)
   - In Setup > Object Manager, delete:
     * LegallyMail Log
     * LegallyMail Template

================================================================================
10. SUPPORT AND CONTACT
================================================================================

If you have problems during installation or use of the component:

Email: support@legallymail.com
Website: https://legallymail.com
Documentation: https://legallymail.com/docs
Support hours: Monday to Friday, 9:00 AM - 6:00 PM (CET)

When contacting support, provide:
- Salesforce version (Setup > Company Information)
- Complete error message
- Steps to reproduce the problem
- Screenshots if possible

================================================================================
END OF DOCUMENT
================================================================================

Version: 1.0
Last updated: February 2026
Developed by: LegallyMail
License: GPLv2 or later
