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
- 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.
- Call
proofpoint_essentials_org_get to confirm the org is active and
check its current domain list.
- 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).
- Instruct the customer to complete DNS verification for each new domain
(TXT record or MX delegation) — the API call alone does not activate
filtering.
- 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
- Call
proofpoint_essentials_org_get to confirm current state and record
it (domains, features, license count) in case of later disputes.
- Call
proofpoint_essentials_org_deactivate with the org name.
- Confirm mail flow protection has stopped by re-checking org state — do
not assume the call succeeded silently; verify.
Offboard a customer permanently
- Confirm with the account owner that deletion (not deactivation) is
intended — this is the destructive path and cannot be undone.
- 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.
- Call
proofpoint_essentials_org_delete with the org name.
Upgrade a customer's package tier
- Call
proofpoint_essentials_org_get and proofpoint_essentials_licensing_get
to confirm current package and seat usage.
- Call
proofpoint_essentials_package_update with the new tier.
- 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
- Call
proofpoint_essentials_token_create for the org to mint a
short-lived Odin-based SSO token.
- 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
1---2name: proofpoint-essentials-org-management3description: Proofpoint Essentials organization lifecycle: get an org and its domains, activate/deactivate, delete, manage domains, toggle features, adjust licensing allocation, change package/subscription tier, and mint an Odin-based SSO token for console handoff.4---56# Proofpoint Essentials Org Management78## Overview910An Essentials **organization** is one customer tenant under an MSP's11reseller account: a set of domains, mailbox-protected users, enabled12features, a license allocation, and a package tier. This skill covers the13org-level lifecycle and everything scoped to the org as a whole rather than14to an individual mailbox. Every call here requires the org's regional pod —15resolve it first with `proofpoint_essentials_endpoint_resolve` (see the16`api-patterns` skill) before calling any tool below.1718## Anti-triggers1920- **Creating or managing individual mailbox users** — that is21 `user-management`. This skill covers the org container, not what's inside22 it.23- **Inbound/outbound mail flow metrics** — that is `reporting`. Org-level24 identity here stops at features, licensing, and package; it does not25 cover message volume or delivery statistics.2627## Key Concepts2829### Org lifecycle states3031| State | Meaning |32|-------|---------|33| Active | Filtering mail flow enabled; domains route through Essentials normally |34| Deactivated | Org suspended — mail flow protection stops, but the org, its domains, and its users are preserved |35| Deleted | Org and its configuration are permanently removed |3637**Deactivate is reversible; delete is not.** Deactivating an org (e.g. for a38non-paying customer, or during an offboarding notice period) preserves39everything so it can be reactivated later. Deleting an org removes its40configuration outright. Always prefer deactivate over delete unless the41customer relationship is definitively over.4243### Domain states4445A domain added to an org must be verified (via DNS TXT record or MX46delegation, configured in the Essentials console) before mail actually47routes through Essentials for it. Adding a domain via the API registers it;48it does not itself complete DNS verification.4950## MCP Tools5152| Tool | Description | Key Parameters |53|------|-------------|----------------|54| `proofpoint_essentials_org_get` | Get an org's details and its domain list | `org_name` |55| `proofpoint_essentials_org_activate` | Reactivate a deactivated org | `org_name` |56| `proofpoint_essentials_org_deactivate` | Suspend an org (reversible) | `org_name` |57| `proofpoint_essentials_org_delete` | Permanently delete an org | `org_name` |58| `proofpoint_essentials_domains_list` | List an org's domains | `org_name` |59| `proofpoint_essentials_domains_create` | Add one or more domains to an org | `org_name`, `domains[]` |60| `proofpoint_essentials_domains_update` | Update a domain's settings | `org_name`, `domain_name` |61| `proofpoint_essentials_domains_delete` | Remove a domain from an org | `org_name`, `domain_name` |62| `proofpoint_essentials_features_get` | View which product features are enabled for an org | `org_name` |63| `proofpoint_essentials_features_update` | Enable/disable product features for an org | `org_name`, `features` |64| `proofpoint_essentials_licensing_get` | View an org's license allocation | `org_name` |65| `proofpoint_essentials_licensing_update` | Modify an org's license allocation | `org_name`, `license_count` |66| `proofpoint_essentials_package_update` | Change an org's subscription/package tier | `org_name`, `package` |67| `proofpoint_essentials_token_create` | Mint an Odin-based SSO token for console handoff | `org_name` |6869`proofpoint_essentials_domains_create` follows the batch-create / 20770Multi-Status pattern described in `api-patterns` when given more than one71domain — check per-domain results rather than treating the call as72all-or-nothing.7374## Common Workflows7576### Onboard a new customer org77781. Confirm the org already exists on the reseller side (Essentials orgs are79 provisioned through the reseller relationship, not created ad hoc via80 this API surface) and resolve its regional pod.812. Call `proofpoint_essentials_org_get` to confirm the org is active and82 check its current domain list.833. Call `proofpoint_essentials_domains_create` with the customer's mail84 domain(s). Check the 207 response for any domain that failed (e.g.85 already claimed by another org).864. Instruct the customer to complete DNS verification for each new domain87 (TXT record or MX delegation) — the API call alone does not activate88 filtering.895. Call `proofpoint_essentials_features_get` and90 `proofpoint_essentials_licensing_get` to confirm the org's package91 includes what the customer purchased.9293### Suspend a non-paying customer without losing configuration94951. Call `proofpoint_essentials_org_get` to confirm current state and record96 it (domains, features, license count) in case of later disputes.972. Call `proofpoint_essentials_org_deactivate` with the org name.983. Confirm mail flow protection has stopped by re-checking org state — do99 not assume the call succeeded silently; verify.100101### Offboard a customer permanently1021031. Confirm with the account owner that deletion (not deactivation) is104 intended — **this is the destructive path and cannot be undone.**1052. Export or record anything needed for compliance/audit before deleting —106 `proofpoint_essentials_org_get`, `proofpoint_essentials_domains_list`,107 `proofpoint_essentials_licensing_get` — since none of it is recoverable108 afterward.1093. Call `proofpoint_essentials_org_delete` with the org name.110111### Upgrade a customer's package tier1121131. Call `proofpoint_essentials_org_get` and `proofpoint_essentials_licensing_get`114 to confirm current package and seat usage.1152. Call `proofpoint_essentials_package_update` with the new tier.1163. Re-check `proofpoint_essentials_features_get` — a package change can117 enable features that were previously unavailable; confirm what actually118 changed rather than assuming the upgrade enabled everything the new tier119 nominally includes.120121### Hand a customer org to a technician for console troubleshooting1221231. Call `proofpoint_essentials_token_create` for the org to mint a124 short-lived Odin-based SSO token.1252. Use the returned token/URL to open the Essentials console scoped to that126 org — do not share the reseller admin's own `X-User`/`X-Password`127 credentials with the technician.128129## Error Handling130131| Symptom | Cause | Resolution |132|---------|-------|------------|133| 404 on `org_get` for an org you can see in the console | Wrong regional pod | Re-run endpoint discovery |134| `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 |135| `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 |136| `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 |137| `org_delete` returns 403 | Credential is a customer-org admin, not a reseller admin | Org deletion typically requires reseller-level admin credentials |138139## Related Skills140141- [Proofpoint Essentials API Patterns](../api-patterns/SKILL.md) - Auth, regional pod resolution, batch semantics142- [Proofpoint Essentials User Management](../user-management/SKILL.md) - Mailbox user CRUD within an org143- [Proofpoint Essentials Reporting](../reporting/SKILL.md) - Inbound/outbound mail flow metrics
WYRE-AI