Exporting Users from Proofpoint Essentials

From the Users Console

After logging into the Proofpoint Essentials Console, navigate to User Management > Users.

After the page loads, at the top of the screen, you will see an option to export CSV. The CSV will export with generic information:

* First Name
* Surname
* Primary Email
* Alias1
* Alias2
* Alias3
etc...

Powershell Script

To copy the script without the referencing numbers, hover over the script to get the Code View and Print Options, click on the Code View (looks like two brackets <>). 

<#
    .REQUIREMENTS
        * API v1 from Proofpoint Essentials
        [Documentation: https://us1.proofpointessentials.com/api/v1/docs/specification.php]

        * Administrator Account for Proofpoint Essentials
            --Organization Admin
            --Channel Admin

    .DESCRIPTION
        This script is intended to use the API (v1) for Proofpoint Essentials to capture and export
        users from the organization and export them into an orderly CSV format. This captures:
          * Primary Email Address
          * First Name
          * Last Name
          * Type of Account
          * Number of Aliases
          * Aliases (comma separated)

    .INPUTS
        * Proofpoint Essentials Console Credentials
        * Domain that you are requesting users from
        * The Data Stack that the domain resides on. This is the beginning portion of your login site:
            (I.E. https://us2.proofpointessentials.com -- us2 would be the stack.)

    .OUTPUTS
        * This will output one (1) CSV file with the user list export.
            ** (SystemDrive, C for example) C:\Temp\UserExport\domain.com\

        * Files Generated from this script
            ** UserList.csv

    .NOTES
        Version:         1.0
        Creation Date:   6/25/2021

    .DISCLAIMER
        This script works in it's current form. Any alterations or adjustments made to this script
        will not be supported or eligible for troubleshooting support. This script is used for
        data gathering only. Proofpoint Essentials Support does not currently offer services
        to troubleshoot scripting solutions or script configurations. This is a working example of
        how the API can be utilized to get management information together for securing your 
        customers and enabling partners with new tools for information. 

#>

#Establish global parameters that will be used throughout the script.
$Global:params = @{
    Domain      = ""
    Stack       = ""
    StackList   = ('us1','us2','us3','us4','us5','eu1')
    Headers     = ""
    Method      = 'GET'
    Body        = ""
    SMTP        = ""
    ContentType = 'application/json'
    FolderName  = ""
}

# This funciton will capture and prepare your credentials for the Proofpoint Essentials API.
function Snag-Creds {
    $domain = $Global:params.Domain
    $Creds = Get-Credential -Message "Enter your Credentials for Proofpoint Essentials."


    $headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
    $headers.Add("X-User",($Creds).UserName)
    $headers.Add("X-Password",($Creds.GetNetworkCredential()).Password)

    $Global:params.Headers = $headers

}

# This function will take the parameters collected in the main script and use them to cycle through
# the sender lists for the organization and each user within the provided domain.
function Snag-Users ($Pdomain) {
    $targetStack = $Global:params.Stack
    $targetDomain = $Pdomain
    $targetCompanyUsers = "https://$targetStack.proofpointessentials.com/api/v1/orgs/$targetDomain/users"
    $AllDomainCheck = '*@'

    $UserResponse = Invoke-RestMethod -Headers $Global:params.Headers -Uri $targetCompanyUsers -Method Get

    ## Export User Safe Sender
    $ExportFolder = "$ENV:SystemDrive\Temp\UserExport\$Pdomain"
    $UserListExport = "$ExportFolder\UserList.csv"
    $UserList = @()
    IF (!(Test-Path $ExportFolder)) {New-Item $ExportFolder -ItemType Directory -Force}
    Write-Output "`nProcessing your request now..."
## Exporting MULTI HashTable
    
    #UserListCreation
    foreach ($item in $UserResponse.users) {
        $AliasCount = $item.alias_emails.count
        $ActualAlias = $item.alias_emails -join ","

        $UserList += @([pscustomobject]@{PrimaryEmail=$item.primary_email;FirstName=$item.firstname;LastName=$item.surname;TypeOfAccount=$item.type;NumberOfAliases=$AliasCount;Aliases=$ActualAlias})

    }

    $UserList | Export-Csv -Path $UserListExport -NoTypeInformation -Force
    
    #Open Explorer Window with new files inside.
    Invoke-Item $ExportFolder
}

# This script will begin with a clean Powershell Window and walk through the credentials capture.
cls
Write-Output "Enter your credentials for Proofpoint.`n"
Snag-Creds

# This will enable you to select the domain that you wish to get information from.
$TargetDomain = Read-Host -Prompt "Which domain are you going to pull sender lists from"

# This is a security check which will only accept appropriate data stacks that we currently use.
$Global:params.Stack = $null
do {
    $Global:params.Stack = (Read-Host "Which data stack are you accessing? (us1,us2,us3,us4,us5,eu1)").ToLower()
    } while ($Global:params.Stack -notin $Global:params.StackList)

# This will execute the main program and generate the files within the selected directory. 
Snag-Users -Pdomain $TargetDomain