Proofpoint Essentials Org Management

Overview

An Essentials organization is one customer tenant under an MSP's reseller account: a set of domains, mailbox-protected users, enabled features, a license allocation, and a package tier. This skill covers the org-level lifecycle and everything scoped to the org as a whole rather than to an individual mailbox. Every call here requires the org's regional pod — resolve it first with proofpoint_essentials_endpoint_resolve (see the api-patterns skill) before calling any tool below.

Anti-triggers

• Creating or managing individual mailbox users — that is user-management. This skill covers the org container, not what's inside it.
• Inbound/outbound mail flow metrics — that is reporting. Org-level identity here stops at features, licensing, and package; it does not cover message volume or delivery statistics.

Key Concepts

Org lifecycle states

State	Meaning
Active	Filtering mail flow enabled; domains route through Essentials normally
Deactivated	Org suspended — mail flow protection stops, but the org, its domains, and its users are preserved
Deleted	Org and its configuration are permanently removed

Deactivate is reversible; delete is not. Deactivating an org (e.g. for a non-paying customer, or during an offboarding notice period) preserves everything so it can be reactivated later. Deleting an org removes its configuration outright. Always prefer deactivate over delete unless the customer relationship is definitively over.

Domain states

A domain added to an org must be verified (via DNS TXT record or MX delegation, configured in the Essentials console) before mail actually routes through Essentials for it. Adding a domain via the API registers it; it does not itself complete DNS verification.

MCP Tools

Tool	Description	Key Parameters
proofpoint_essentials_org_get	Get an org's details and its domain list	org_name
proofpoint_essentials_org_activate	Reactivate a deactivated org	org_name
proofpoint_essentials_org_deactivate	Suspend an org (reversible)	org_name
proofpoint_essentials_org_delete	Permanently delete an org	org_name
proofpoint_essentials_domains_list	List an org's domains	org_name
proofpoint_essentials_domains_create	Add one or more domains to an org	org_name, domains[]
proofpoint_essentials_domains_update	Update a domain's settings	org_name, domain_name
proofpoint_essentials_domains_delete	Remove a domain from an org	org_name, domain_name
proofpoint_essentials_features_get	View which product features are enabled for an org	org_name
proofpoint_essentials_features_update	Enable/disable product features for an org	org_name, features
proofpoint_essentials_licensing_get	View an org's license allocation	org_name
proofpoint_essentials_licensing_update	Modify an org's license allocation	org_name, license_count
proofpoint_essentials_package_update	Change an org's subscription/package tier	org_name, package
proofpoint_essentials_token_create	Mint an Odin-based SSO token for console handoff	org_name

proofpoint_essentials_domains_create follows the batch-create / 207 Multi-Status pattern described in api-patterns when given more than one domain — check per-domain results rather than treating the call as all-or-nothing.

Common Workflows

Onboard a new customer org

1. Confirm the org already exists on the reseller side (Essentials orgs are provisioned through the reseller relationship, not created ad hoc via this API surface) and resolve its regional pod.
2. Call proofpoint_essentials_org_get to confirm the org is active and check its current domain list.
3. Call proofpoint_essentials_domains_create with the customer's mail domain(s). Check the 207 response for any domain that failed (e.g. already claimed by another org).
4. Instruct the customer to complete DNS verification for each new domain (TXT record or MX delegation) — the API call alone does not activate filtering.
5. Call proofpoint_essentials_features_get and proofpoint_essentials_licensing_get to confirm the org's package includes what the customer purchased.

Suspend a non-paying customer without losing configuration

1. Call proofpoint_essentials_org_get to confirm current state and record it (domains, features, license count) in case of later disputes.
2. Call proofpoint_essentials_org_deactivate with the org name.
3. Confirm mail flow protection has stopped by re-checking org state — do not assume the call succeeded silently; verify.

Offboard a customer permanently

1. Confirm with the account owner that deletion (not deactivation) is intended — this is the destructive path and cannot be undone.
2. Export or record anything needed for compliance/audit before deleting — proofpoint_essentials_org_get, proofpoint_essentials_domains_list, proofpoint_essentials_licensing_get — since none of it is recoverable afterward.
3. Call proofpoint_essentials_org_delete with the org name.

Upgrade a customer's package tier

1. Call proofpoint_essentials_org_get and proofpoint_essentials_licensing_get to confirm current package and seat usage.
2. Call proofpoint_essentials_package_update with the new tier.
3. Re-check proofpoint_essentials_features_get — a package change can enable features that were previously unavailable; confirm what actually changed rather than assuming the upgrade enabled everything the new tier nominally includes.

Hand a customer org to a technician for console troubleshooting

1. Call proofpoint_essentials_token_create for the org to mint a short-lived Odin-based SSO token.
2. Use the returned token/URL to open the Essentials console scoped to that org — do not share the reseller admin's own X-User/X-Password credentials with the technician.

Error Handling

Symptom	Cause	Resolution
404 on org_get for an org you can see in the console	Wrong regional pod	Re-run endpoint discovery
domains_create 207 with a failed entry	Domain already claimed by another org, or malformed domain string	Inspect the per-item error; do not resubmit the whole batch
org_deactivate succeeds but mail still appears to flow	DNS/MX still pointed at Essentials from the customer's registrar	Deactivation stops Essentials-side processing; it does not change the customer's DNS
package_update succeeds but a feature is still unavailable	Feature requires a separate toggle	Call proofpoint_essentials_features_update explicitly — package tier changes seat/feature eligibility, not necessarily every feature's on/off state
org_delete returns 403	Credential is a customer-org admin, not a reseller admin	Org deletion typically requires reseller-level admin credentials

Related Skills

• Proofpoint Essentials API Patterns - Auth, regional pod resolution, batch semantics
• Proofpoint Essentials User Management - Mailbox user CRUD within an org
• Proofpoint Essentials Reporting - Inbound/outbound mail flow metrics