proofpoint-essentials-api-patterns

# Proofpoint Essentials API Patterns ## Overview Proofpoint Essentials is Proofpoint's SMB/MSP-tier email security product — a distinct product, API, and credential model from Proofpoint TAP (Targeted Attack Protection). Essentials is managed through a REST API scoped to **customer organizations** under an MSP's reseller account: get/activate/ deactivate/delete an org, manage its domains and mailbox users, toggle features, adjust licensing and package tier, and pull inbound/outbound mail flow reports. This skill covers authentication, regional routing, base URL construction, batch semantics, and error handling shared by every other skill in this plugin. ## Anti-triggers - **Proofpoint TAP, quarantine, forensics, URL Defense, or VAP/people-risk data** — that is a completely different product, API, and auth model (service-principal HTTP Basic Auth against `tap-api.proofpoint.com`). Use the sibling `proofpoint` plugin's `proofpoint-api-patterns` skill instead. - **Checkpoint Harmony (Avanan), Abnormal, Mimecast, or another vendor's email-security API** — this skill only speaks the Proofpoint Essentials API. ## Key Concepts ### One credential shape, two admin scopes Every Essentials API call carries the same two headers regardless of which resource it touches: ```http X-User: admin@msp-reseller.com X-Password: *** ``` **Org-admin credentials only.** Unlike TAP's per-request service principal, Essentials authenticates as an actual admin login — either a reseller-level admin (who can act on any customer org the reseller manages) or a customer-org admin (scoped to that one org). There is no separate API key/secret pair to generate; the credentials are the same ones used to sign into the Essentials web console, so credential rotation means a password change, not a re-issued key. ### Region and base URL ``` https://{region}.proofpointessentials.com/api/v1/ ``` | Region | Notes | |--------|-------| | `us1` | Default / anchor pod — also answers endpoint-discovery requests for orgs hosted elsewhere | | `us2`, `eu1`, and other regional pods | Where a given customer org's data actually lives | Every customer organization is homed on exactly one regional pod. Calling the wrong pod for an org's resource endpoints (domains, users, reporting, etc.) fails — it does not proxy or redirect. `us1` is the default entry point and also the endpoint-discovery anchor: even for an org that lives on `eu1`, you resolve its pod by asking `us1` first (see below), then send every subsequent call for that org to the resolved pod. ### Endpoint discovery — resolve the pod before doing anything else Before calling any org-scoped resource for an organization you have not already resolved, call `proofpoint_essentials_endpoint_resolve` (backed by the discovery endpoint under `us1`) with the org's primary domain or org name. The response identifies the regional pod that hosts the org. Cache that mapping for the session — do not re-resolve on every call, but do not assume yesterday's mapping still holds after a reseller migrates a customer between pods. **Every workflow in this plugin starts here.** `org-management`, `user-management`, and `reporting` all assume the caller already knows which region an org lives on. If you skip discovery and guess `us1`, an org on `eu1` fails outright rather than silently returning empty data. ## Common Workflows ### First contact with an unfamiliar org 1. Call `proofpoint_essentials_endpoint_resolve` with the org's primary domain to get its regional pod. 2. Build every subsequent request's base URL from that region. 3. Call `proofpoint_essentials_org_get` to confirm the org resolves and pull its domain list before doing anything else. ### Batch operations and 207 Multi-Status `proofpoint_essentials_users_create` and `proofpoint_essentials_domains_create` both accept an array of objects in a single call — creating many mailbox users or adding many domains at once. The API replies with **HTTP 207 Multi-Status**, not a single success/failure code: the response body carries a per-item result, and a partial batch can contain both successes and failures in the same response. **Never treat a 207 as a blanket success.** Iterate the per-item results and report exactly which entries succeeded and which failed (and why) — a batch of 50 users where 3 failed on a duplicate mailbox address is not "created 50 users." Retry only the failed entries; resubmitting the whole batch will re-fail (or duplicate) the entries that already succeeded. ## Error Handling | Code | Meaning | Action | |------|---------|--------| | 200 | Success | Process response | | 207 | Multi-status (batch create) | Inspect each item's result individually | | 400 | Malformed request / invalid field value | Check request body against the field reference for that resource | | 401 | Invalid `X-User`/`X-Password` | Re-verify credentials; a customer-org admin cannot authenticate against a different org | | 403 | Authenticated but not authorized for this org | The credential is scoped to a different org than the one requested | | 404 | Org, domain, or user not found | Confirm the identifier and that the request went to the correct regional pod | | 429 | Rate limited | Back off and retry; Essentials does not publish fixed numeric limits, so treat 429 as authoritative rather than pre-computing a budget | | 5xx | Upstream/pod error | Retry with backoff; if persistent, the regional pod itself may be degraded | ### Common mistakes | Symptom | Cause | Fix | |---------|-------|-----| | 404 on an org you know exists | Calling the wrong regional pod | Re-run endpoint discovery; the org may have moved pods | | 401 with credentials that work in the console | Reseller vs. customer-org admin mismatch | Reseller admins can act on any managed org; customer-org admins cannot act outside their own org | | Batch call "succeeds" but half the users are missing | 207 was treated as 200 | Parse per-item results, not just the top-level status code | | Reporting call returns empty for a known-active org | Region resolved to the wrong pod, or the date range is outside retained data | Re-check regional resolution first, then narrow the date range | ## Related Skills - [Proofpoint Essentials Org Management](../org-management/SKILL.md) - Organizations, domains, features, licensing, package tier - [Proofpoint Essentials User Management](../user-management/SKILL.md) - Mailbox user CRUD - [Proofpoint Essentials Reporting](../reporting/SKILL.md) - Inbound/outbound mail flow metrics