> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neoagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connecting Proofpoint Essentials to Neo

> Save a Proofpoint Essentials admin login in Neo, and decide what each agent can do

You connect Proofpoint Essentials once at the MSP level, then turn it on per agent.

<Info>
  The Proofpoint Essentials API signs in with an admin account's username and password. There is no API key. Neo stores both in Azure Key Vault.
</Info>

## 1. Create an admin account for Neo

<Steps>
  <Step title="Use a dedicated admin">
    In the Proofpoint Essentials console, create an admin account for Neo, so you can see its changes in the audit trail and revoke it on its own.

    Use a **Channel Partner Admin** at your partner level to give Neo access to every client organization. An **Organization Admin** reaches only its own organization.
  </Step>

  <Step title="Make it the service account">
    Proofpoint lets one admin account per organization be the **service account**, which is not billable and does not count toward licences.
  </Step>

  <Step title="Keep the login local">
    Neo signs in with the username and password on every call. If the account signs in through SSO or MFA and Neo's login is refused, use a local admin account without them.
  </Step>
</Steps>

## 2. Add the login in Neo

<Steps>
  <Step title="Open Integrations">
    In the Neo Dashboard, open **Integrations** and find the Proofpoint Essentials card, under Security.
  </Step>

  <Step title="Enter your stack">
    Enter the stack your account is on. It is the first part of the address you sign in at: `us2` in `us2.proofpointessentials.com`.
  </Step>

  <Step title="Save the login">
    Enter the admin username and password and click **Save**. Neo checks the login against Proofpoint before saving, so a wrong password or the wrong stack is rejected straight away. The **Organization Mapping** tab fills separately after the save, and again on each nightly PSA sync.
  </Step>
</Steps>

## 3. Turn Proofpoint Essentials on per agent

Each agent decides whether it uses Proofpoint Essentials and which areas it can touch. Open the agent, go to the Integrations section, and configure the Proofpoint Essentials block.

### Pick an access profile

<CardGroup cols={3}>
  <Card title="Read Only" icon="magnifying-glass">
    Every area read only. The agent finds the organization, user and sender lists, and reports.
  </Card>

  <Card title="Helpdesk" icon="headset">
    Sender Lists and Users set to read and write. Everything else read only. Fits the "please let this sender through" ticket.
  </Card>

  <Card title="IT Admin" icon="user-gear">
    Every area read and write except Licensing & Products and Reporting & Billing.
  </Card>
</CardGroup>

### Or set each area by hand

| Area                      | Access levels you can pick          | Notes                                                                                                     |
| ------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------- |
| **Sender Lists**          | Disabled, Read Only, Read and Write | Safe and block lists per organization, user or group. Clearing a whole list always waits on a technician. |
| **Users**                 | Disabled, Read Only, Read and Write | Deleting a user, setting a password and granting an admin role always wait on a technician.               |
| **Organizations**         | Disabled, Read Only, Read and Write | Creating a client organization always waits on a technician.                                              |
| **Domains**               | Disabled, Read Only, Read and Write | Deleting a domain or a DKIM key always waits on a technician.                                             |
| **Organization Settings** | Disabled, Read Only, Read and Write | Resetting the Azure AD user sync always waits on a technician.                                            |
| **Login & SSO**           | Disabled, Read Only, Read and Write | Every change always waits on a technician.                                                                |
| **Licensing & Products**  | Disabled, Read Only                 | Licence counts, package and products.                                                                     |
| **Reporting & Billing**   | Disabled, Read Only                 | Mail flow statistics and billing figures.                                                                 |

## Safety controls

* **Quarantine is out of reach.** Proofpoint's published Essentials API document has no quarantine endpoint, and Neo sends only published operations, so no agent can release a message. The agent tells the user or technician how to release it.
* **Never allowed.** Neo never deletes a client organization and never creates a login token that signs in as another user, whatever the agent is set to.
* **Always waits on a technician.** Clearing a sender list; deleting a user, domain or DKIM key; setting a user's password or admin role; creating a client organization; resetting the Azure AD sync; and every login, MFA or SSO change. This holds regardless of the agent's automation level or the access profile you picked.
* **Licensing and billing are read only.** Neo cannot buy a product or change a licence count.
* **Only published operations.** Neo sends only the operations Proofpoint documents. Suspicious URL paths (anything containing `..`, for example) are rejected before they reach Proofpoint.

## If Proofpoint refuses Neo's requests

| What comes back                                                              | Cause                                                                           | Fix                                                                 |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `401`                                                                        | The password changed, the account was removed, or the saved stack is wrong      | Re-enter the login in Neo and check the stack                       |
| `403`                                                                        | The admin cannot reach that organization, or the account type has no API access | Use a Channel Partner Admin for access to every client organization |
| `404`                                                                        | The domain is not registered to an organization this login can see              | Check the client's domains in the Proofpoint console                |
| A failed **Proofpoint Essentials Company Mapping** row with a `401` or `403` | The same login problem, met by the nightly mapping                              | Fix the login as above. The next PSA sync rebuilds the mapping      |

Until a `401` or `403` is fixed, agents that use Proofpoint Essentials report the failure on the ticket they were working. The rest of Neo keeps running.

## Disconnecting Proofpoint Essentials

<Steps>
  <Step title="Open the integration">
    In the Neo Dashboard, open **Integrations** and select the Proofpoint Essentials card.
  </Step>

  <Step title="Disconnect">
    Click **Disconnect** and confirm. Neo removes the login from Key Vault. Agents that use Proofpoint Essentials stop working until you connect it again.
  </Step>
</Steps>

Your Organization Mapping is kept, including any mapping you set by hand, so reconnecting later picks up where you left off.

## Security

* The admin login lives in Azure Key Vault. It is never stored in plaintext.
* All traffic to Proofpoint goes over HTTPS, to your stack's `proofpointessentials.com` host.
* Write access is opt in per agent and per area.