Cross-Tenant Email Forwarding Suite

A comprehensive PowerShell solution for securely configuring and monitoring email forwarding between Microsoft 365 tenants (cross-tenant scenarios).

🎯 Overview

This suite provides three powerful scripts to manage cross-tenant SMTP email forwarding in Exchange Online:

• Set-CrossTenantForwarding.ps1 - Configure forwarding for a single user
• Set-CrossTenantForwarding-Batch.ps1 - Bulk configure forwarding from a CSV file
• Monitor-CrossTenantForwarding.ps1 - Monitor and validate forwarding delivery

✨ Features

Security & Compliance

• ✅ Secure Exchange Online authentication with MFA support
• ✅ Remote Domain configuration for cross-tenant scenarios
• ✅ Outbound spam policy management
• ✅ Comprehensive audit logging (CSV export)
• ✅ Full error handling and validation

Operational Features

• 📋 Batch processing with CSV import
• 🔍 Real-time email trace monitoring (Get-MessageTraceV2)
• 📊 Detailed statistics and success rates
• 🛡️ WhatIf mode for dry-run testing
• 📝 Structured logging with timestamps
• ⏸️ Continue-on-error option for batch operations

User Experience

• 🎨 Color-coded console output
• 📋 Professional structured reports
• ⚙️ Automatic module installation/upgrade
• 🔐 Secure credential handling
• 📄 Pre/post-configuration validation

📋 Prerequisites

System Requirements

• PowerShell: 5.1+ (Windows PowerShell) or PowerShell 7+
• Windows: Windows 10/11 or Windows Server 2016+
• Network: Internet connectivity to Microsoft 365

Microsoft 365 Requirements

• License: Microsoft 365 Business Premium or higher
• Modules: ExchangeOnlineManagement 3.0.0+ (auto-installed)
• Permissions:
  • Global Administrator, or
  • Exchange Administrator role

🚀 Quick Start

Installation

1. Clone this repository:

git clone https://github.com/yourusername/cross-tenant-forwarding.git
cd cross-tenant-forwarding

2. Verify PowerShell version:

$PSVersionTable.PSVersion

3. Run scripts (modules auto-install):

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Single User Setup

.\Set-CrossTenantForwarding.ps1 `
    -SourceUserUPN "john.doe@company.com" `
    -TargetEmailAddress "john.doe@partner.com" `
    -TargetDomain "partner.com" `
    -KeepCopyInSource $true

Bulk User Setup

1. Create a CSV file with columns:

   • SourceUserUPN (required)
   • TargetEmailAddress (required)
   • TargetDomain (required)
   • KeepCopyInSource (TRUE/FALSE)
   • Comments (optional)

2. Run batch script:

.\Set-CrossTenantForwarding-Batch.ps1 -CSVPath "Users_Forwarding.csv"

Monitoring

.\Monitor-CrossTenantForwarding.ps1 `
    -SourceRecipient "john.doe@company.com" `
    -TargetRecipient "john.doe@partner.com" `
    -DaysBack 7

📚 Documentation

• DOCUMENTATION.md - French technical documentation
• DOCUMENTATION_EN.md - English technical documentation

Key Documentation Topics

For Set-CrossTenantForwarding.ps1

• Parameter details
• Configuration flow (6 steps)
• Security recommendations
• Troubleshooting guide

For Set-CrossTenantForwarding-Batch.ps1

• CSV format requirements
• Error handling strategies
• WhatIf mode usage
• Report interpretation

For Monitor-CrossTenantForwarding.ps1

• Message trace methodology
• Email matching logic
• Delay measurements
• Statistics interpretation

📁 Project Structure

cross-tenant-forwarding/
├── Set-CrossTenantForwarding.ps1        # Single user setup
├── Set-CrossTenantForwarding-Batch.ps1  # Bulk setup
├── Monitor-CrossTenantForwarding.ps1    # Monitoring
├── Users_Forwarding.csv                 # Example CSV
├── README.md                             # This file
├── DOCUMENTATION.md                      # French docs
├── DOCUMENTATION_EN.md                   # English docs
├── CONTRIBUTING.md                       # Contributing guide
├── LICENSE                               # MIT License
└── .gitignore                            # Git ignore rules

🔧 Usage Examples

Example 1: Single User with Copy Retention

.\Set-CrossTenantForwarding.ps1 `
    -SourceUserUPN "marie.dupont@company.fr" `
    -TargetEmailAddress "marie.dupont@newcompany.fr" `
    -TargetDomain "newcompany.fr" `
    -KeepCopyInSource $true

Result: Marie's emails are forwarded to the new address AND kept in the original mailbox.

Example 2: Test Before Applying

# View what would happen without making changes
.\Set-CrossTenantForwarding-Batch.ps1 `
    -CSVPath "Users_Forwarding.csv" `
    -WhatIf

Example 3: Bulk Apply with Error Handling

# Continue processing even if some users fail
.\Set-CrossTenantForwarding-Batch.ps1 `
    -CSVPath "Users_Forwarding.csv" `
    -ContinueOnError $true

Example 4: Verify Forwarding After 24 Hours

# Check delivery status after emails have been sent
.\Monitor-CrossTenantForwarding.ps1 `
    -SourceRecipient "marie.dupont@company.fr" `
    -TargetRecipient "marie.dupont@newcompany.fr" `
    -DaysBack 1  # Last 24 hours

📊 Output Files

Batch Processing Generates:

• BatchForwarding_[timestamp].log - Full operation log
• BatchForwarding_Report_[timestamp].csv - Configuration results
• BatchForwarding_Errors_[timestamp].csv - Error details

Single User Configuration Generates:

• CrossTenantForwarding_[timestamp].log - Operation log
• ForwardingAudit_[date].csv - Audit trail

🛡️ Security & Compliance

Built-in Security Features

1. Authentication

   • MFA-ready authentication flow
   • Secure token handling
   • Connection state validation

2. Audit Trail

   • All operations logged with timestamps
   • Administrator tracking
   • Compliance reports in CSV format

3. Data Protection

   • Remote Domain controls
   • Outbound spam policy validation
   • Copy retention options

Recommended Post-Configuration

1. Enable Alerts in Microsoft Defender

   • Monitor "Creation of forwarding/redirect rule"
   • Alert on suspicious forwarding changes

2. Configure DLP (Data Loss Prevention)

   • Add target domain to approved recipients
   • Monitor data exfiltration risks

3. Enable Audit

   • Monitor Set-Mailbox operations
   • Track forwarding configuration changes

4. Regular Review

   • Audit forwarding rules monthly
   • Remove old/unused forwarding rules

🐛 Troubleshooting

Common Issues

Issue: "Module not found"

# Solution: Auto-install will run on first execution
# Or manually install:
Install-Module ExchangeOnlineManagement -MinimumVersion 3.0.0 -Force

Issue: "Mailbox not found"

# Verify UPN format is correct: user@domain.com
# Check user exists in source tenant:
Get-EXOMailbox -Identity "user@domain.com"

Issue: "AutoForwardingMode is Off"

# Solution: Script automatically enables this
# But verify in Microsoft 365 Defender if needed:
Get-HostedOutboundSpamFilterPolicy -Identity Default

Issue: "Remote Domain exists but forwarding fails"

# Ensure domain is properly configured:
Get-RemoteDomain | Where-Object {$_.DomainName -eq "targetdomain.com"}

See full troubleshooting in DOCUMENTATION_EN.md

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see LICENSE file for details.

⚠️ Disclaimer

This suite is provided AS-IS. While thoroughly tested, always:

• ✅ Test in a non-production environment first
• ✅ Use WhatIf mode for batch operations
• ✅ Ensure proper backups and disaster recovery plans
• ✅ Have a rollback plan for critical changes
• ✅ Follow your organization's change management procedures

📞 Support

• Documentation: See DOCUMENTATION_EN.md
• Issues: Create an issue on GitHub
• Microsoft Learn: Exchange Online forwarding documentation

🔄 Version History

Version 2.1

• Fixed empty string validation in logging
• Enhanced error handling for module installation
• Improved MFA support messages
• Added confirmation prompts for critical operations

Version 2.0

• Added Batch processing script
• Implemented CSV import functionality
• Added monitoring script with message trace
• Enhanced audit logging

Version 1.0

• Initial single-user forwarding configuration
• Basic Remote Domain setup
• Log file generation

🎓 Learn More

• Microsoft Exchange Online Documentation
• Remote Domains in Exchange Online
• Message Trace in Exchange Online

---

Created with ❤️ for Exchange Online administrators

Made for system engineers who love PowerShell, mountains, and well-organized infrastructure 🏔️