Proofpoint Essentials

Overview

Proofpoint Essentials — marketed to MSPs as Proofpoint 365 Total Protection — is a cloud email security platform for small and medium businesses. It filters inbound and outbound mail for spam, viruses, malicious attachments, imposter/BEC and phishing, and adds continuity, encryption and archiving depending on the package.

It is multitenant by design, which is what makes it useful to report on: your MSP holds a partner organization and every client sits underneath it as a child organization. One admin login reaches all of them.

Bumblebee connects through the Essentials Interface API and can retrieve your client roster, mailflow and threat volumes per client, time-bucketed traffic trends, licensing, billing rows, and per-mailbox seat detail.

The integration is read-only. Bumblebee can report on your Proofpoint configuration and traffic but cannot create or modify organizations, users, domains or policies.

How the account is structured

Knowing Proofpoint's object model makes the tools easier to ask for:

• Organization — the tenant, always addressed by a domain rather than an ID. Types are oem_partner, strategic_partner, channel and organization. Your MSP is one of the partner types; each managed client is an organization beneath it.
• Domain — an organization owns one primary domain plus any number of additional ones. Any of them identifies the organization to the API.
• User — a mailbox. Not every user is billable: shared, silent and functional accounts may not consume a licence.
• Package — the licensing tier (Beginner, Business, Advanced, Professional and their Plus variants), which decides what the client gets and what you're billed for.

What is not included

Per-event threat data — individual blocked messages and URL clicks — comes from Proofpoint's separate Essentials Threat API, which uses a different host and its own integration key. That is not part of this integration yet. Enterprise Proofpoint (TAP / Threat Insight Dashboard) is a different product with a different API and is not covered here either.

Prerequisites & Setup

Proofpoint Essentials has no API keys. The API authenticates with an administrator's ordinary console login, so setup is about choosing and preparing the right admin account.

1. Choose the admin login

As an MSP you want a partner-level admin. Consider creating a dedicated account for Bumblebee rather than reusing a person's login — it can be rotated or revoked without locking anyone out.

2. Enable service access

This step is mandatory and is the most common cause of a failed connection.

1. Sign in to Proofpoint Essentials (for example us1.proofpointessentials.com, or whichever stack your account is on).
2. Open the Users and Groups tab.
3. Select the admin user from step 1.
4. Tick Is Imitable (Service Access).
5. Click Save and confirm the user record updated.

Without this flag, a correct email and password still return 401 Unauthorized.

3. Note your regional stack (optional)

Essentials is split across regional stacks — us1 through us5, eu1 and others — and your data is served only from your own. The stack is the prefix of the address bar when you're signed in: us3.proofpointessentials.com means your region is us3.

Bumblebee detects this automatically when you save, so you only need it if detection fails.

Configure in Bumblebee

1. Go to the Integrations page in Bumblebee
2. Select Proofpoint Essentials
3. Enter the admin email address and password
4. Leave Region blank unless step 3 applies
5. Save the configuration
6. Run a test request (e.g. list organizations) from the validation card

Saving calls Proofpoint to resolve your regional stack, so a wrong password or a missing Is Imitable flag fails at that point rather than silently later.

Available Tools

All tools are read-only, and every one takes a domain — any domain belonging to the organization you're asking about. Pass your partner domain for roll-ups across clients, or a client's domain to scope to that client.

Finding your way around

• get_me — whose credentials these are. Returns your partner domain (the one that unlocks roll-ups) and your admin type, so the agent knows whether cross-client data is available.
• list_organizations — the client roster: name, primary domain, package, trial flag, licensed seats, active users and renewal date, one row per managed client.
• get_organization — one organization in full: every domain it owns, how mail reaches Proofpoint (Microsoft 365 integrated or MX routing), package, seat counts, outgoing servers, sender lists and the admin contact.

Mailflow and threats

• get_org_stats — the core reporting tool. Per organization, over the last 1, 7, 30 or 90 days: total inbound and outbound messages, everything blocked in each direction, the inbound threat breakdown (spam, virus, malicious attachment, imposter, phishing), outbound encrypted mail, and active users. With children included, one call covers every client.
• get_org_reporting — the same traffic for one organization broken down over time, hourly for a single day and daily otherwise, so you can see the shape of a spike rather than just its total. Covers clean, spam, virus, fraud, blocklist, safelist and attachment-defended mail, inbound and outbound.

Licensing, billing and seats

• get_licensing — licence count, package and trial flag for one organization. Compare the licence count against active users to spot clients paying for seats they don't use.
• get_billing — the reconciliation view behind your Proofpoint invoice: billable package, confirmed, active and non-billable user counts, billing method, renewal and trial end dates, per client.
• list_users — seat-level detail for one organization: email, name, user type, active and billable flags, aliases and last login.

Things to know

• Spam overlaps the other threat counts. In get_org_stats, ib_spam includes every message marked as spam, including those also classified as imposter or phishing. The threat fields don't sum to it.
• Active users are not licensed seats. active_users counts mailboxes that actually sent or received mail in the period. Compare it with license_count from get_licensing for utilisation.
• The reporting periods differ. get_org_stats accepts 90 days; get_org_reporting tops out at 30.
• A new tenant reports zeros, not errors. Before any mail has flowed, the stats endpoints answer with well-formed zero counts.

Troubleshooting