### Bootstrap Workspace with Python Environment

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/README.md

Paste this prompt into your AI assistant after the workspace is open to bootstrap it: create a Python virtual environment, install requests, copy credentials.json.template to credentials.json, and verify api-reference.json exists. The assistant must stop after completing these tasks and avoid opening another workspace, explaining steps, asking questions, running example scripts, or modifying git state.

```text
You are running inside the Mimecast-API-Action-Pack VS Code workspace. Tasks:
1. Create a Python virtual environment named .venv in the workspace root.
2. Activate the virtual environment.
3. Install requests.
4. Create credentials.json by copying credentials.json.template.
5. Verify api-reference.json exists.
6. Stop.
Do NOT:
- Open or generate another workspace
- Explain steps
- Ask questions
- Run example scripts
- Modify git state
```

--------------------------------

### Run powershell-basic.ps1 with POST and create-user

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/powershell-basic.ps1.md

Command to run the PowerShell example with the specified target method and path.

```powershell
powershell examples/powershell-basic.ps1 -TargetMethod POST -TargetPath "/api/user/create-user"
```

--------------------------------

### Basic execution command for python-basic.py

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/python-basic.py.md

Run the script from the examples directory to execute the main() function.

```bash
cd examples && python python-basic.py
```

--------------------------------

### Endpoint record example from api-reference.json

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/types.md

Canonical example of an Endpoint record from the endpoints array in api-reference.json. All 257 endpoints carry all 9 fields; this is the first record. The path may contain {placeholder} segments that must be substituted before calling, and description is null for 188 of 257 endpoints.

```json
{
  "id": "emergency-contact",
  "name": "Emergency Contact",
  "category": "Account Management",
  "method": "GET",
  "path": "/account/cloud-gateway/v1/emergency-contact",
  "description": null,
  "parameters": [],
  "url": "https://developer.services.mimecast.com/docs/accountmanagement/1/routes/account/cloud-gateway/v1/emergency-contact/get",
  "last_updated": "2025-12-12T14:43:05.688832+00:00"
}
```

--------------------------------

### Metadata object JSON example

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/types.md

Example of the metadata object in api-reference.json. It includes the source URL, scrape timestamp, total endpoint count, and category labels used verbatim by the category filter of tools/find_endpoint.py --category.

```json
{
  "source": "https://developer.services.mimecast.com/apis",
  "scraped_at": "2025-12-12T14:52:57.838923Z",
  "total_endpoints": 257,
  "categories": [
    "Archivedataaccess", "Audit Events", "Account Management",
    "Policy Management", "Threatssecurity Eventsanddataforcg",
    "Threat Management", "Domain Management",
    "Emailsecurityonboarding", "Connector", "Cloud Gateway",
    "Userandgroup Management", "Awareness Training"
  ]
}
```

--------------------------------

### Basic usage examples

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/find_endpoint.py.md

Shows basic invocations of the script: searching for 'blocked senders' and using the --category and --limit options.

```bash
python tools/find_endpoint.py blocked senders
python tools/find_endpoint.py quarantine --category "Cloud Gateway" --limit 5
```

--------------------------------

### GET /connector/cloud-gateway/v1/connectors

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves a list of connectors.

```APIDOC
## GET /connector/cloud-gateway/v1/connectors

### Description
Retrieves a list of connectors.

### Method
GET

### Endpoint
/connector/cloud-gateway/v1/connectors
```

--------------------------------

### Basic call to Resolve-CredentialsPath

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/powershell-basic.ps1.md

Example of calling Resolve-CredentialsPath with a relative path. If the result is $null, the script throws an error.

```powershell
$resolved = Resolve-CredentialsPath -Path "../credentials.json"
if ($null -eq $resolved) { throw "Credentials file not found" }
```

--------------------------------

### GET /directory/cloud-gateway/v1/integrations

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves a list of directory integrations.

```APIDOC
## GET /directory/cloud-gateway/v1/integrations

### Description
Retrieves a list of directory integrations.

### Method
GET

### Endpoint
/directory/cloud-gateway/v1/integrations
```

--------------------------------

### Basic Invoke-MimecastApi call

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/powershell-basic.ps1.md

Basic usage example. Calls Invoke-MimecastApi with credentials, token, and endpoint details, then converts the response to JSON with depth 6.

```powershell
$response = Invoke-MimecastApi -BaseUrl $creds.BaseUrl -Token $token -Method $endpoint.method -Path $endpoint.path -Body $body
$response | ConvertTo-Json -Depth 6
```

--------------------------------

### Main block of powershell-basic.ps1

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/powershell-basic.ps1.md

Main block of the PowerShell example that orchestrates the Mimecast API flow: retrieves credentials, resolves the endpoint, obtains a token, and invokes the API with an empty body, then prints the response as JSON at depth 6.

```powershell
$creds = Get-CredentialsJson -Path $CredsPath
$endpoint = Get-Endpoint -ApiPath $TargetPath -Method $TargetMethod -JsonPath $ApiRefPath
$token = Get-MimecastToken -BaseUrl $creds.BaseUrl -ClientId $creds.ClientId -ClientSecret $creds.ClientSecret
$body = @{}
$response = Invoke-MimecastApi -BaseUrl $creds.BaseUrl -Token $token -Method $endpoint.method -Path $endpoint.path -Body $body
$response | ConvertTo-Json -Depth 6
```

--------------------------------

### GET /role/cloud-gateway/v1/roles

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves a list of roles.

```APIDOC
## GET /role/cloud-gateway/v1/roles

### Description
Retrieves a list of roles.

### Method
GET

### Endpoint
/role/cloud-gateway/v1/roles
```

--------------------------------

### GET /threats/v1/stats/gateway-detections

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves gateway detection statistics.

```APIDOC
## GET /threats/v1/stats/gateway-detections

### Description
Retrieves gateway detection statistics.

### Method
GET

### Endpoint
/threats/v1/stats/gateway-detections

```

--------------------------------

### GET /journaling/cloud-gateway/v1/services

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves a list of journaling services.

```APIDOC
## GET /journaling/cloud-gateway/v1/services

### Description
Retrieves a list of journaling services.

### Method
GET

### Endpoint
/journaling/cloud-gateway/v1/services
```

--------------------------------

### Error handling for load_endpoint

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/python-basic.py.md

Error handling example for load_endpoint: wraps the call in a try/except block to catch the SystemExit exception raised when no endpoint matches, printing the exception message.

```python
try:
    load_endpoint("/does/not/exist", "GET", API_REF_PATH)
except SystemExit as exc:
    print(f"lookup failed: {exc}")
```

--------------------------------

### Error handling for Get-CredentialsJson

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/powershell-basic.ps1.md

Error handling example for Get-CredentialsJson. Wraps the call in a try/catch block, writes an error message with the exception, and exits with code 1 on failure.

```powershell
try {
    $creds = Get-CredentialsJson -Path $CredsPath
} catch {
    Write-Error "Aborting: $_"
    exit 1
}
```

--------------------------------

### GET /policy-management/cloud-gateway/v1/anti-spoofing-bypass/policies

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves a list of anti-spoofing bypass policies.

```APIDOC
## GET /policy-management/cloud-gateway/v1/anti-spoofing-bypass/policies

### Description
Retrieves a list of anti-spoofing bypass policies.

### Method
GET

### Endpoint
/policy-management/cloud-gateway/v1/anti-spoofing-bypass/policies

```

--------------------------------

### Invoke-MimecastApi with error handling

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/powershell-basic.ps1.md

Error handling example. Wraps the API call in a try/catch block and writes an error message with the exception message on failure.

```powershell
try {
    $response = Invoke-MimecastApi -BaseUrl $creds.BaseUrl -Token $token -Method "POST" -Path "/api/user/create-user" -Body @{ data = @(@{ emailAddress = "user@example.com" }) }
} catch {
    Write-Error "API call failed: $($_.Exception.Message)"
}
```

--------------------------------

### GET /siem/v1/batch/events/cg

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves batch SIEM events for Cloud Gateway.

```APIDOC
## GET /siem/v1/batch/events/cg

### Description
Retrieves batch SIEM events for Cloud Gateway.

### Method
GET

### Endpoint
/siem/v1/batch/events/cg

```

--------------------------------

### GET /policy-management/cloud-gateway/v1/anti-spoofing-bypass/policies

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves a list of anti-spoofing bypass policies.

```APIDOC
## GET /policy-management/cloud-gateway/v1/anti-spoofing-bypass/policies

### Description
Retrieves a list of anti-spoofing bypass policies.

### Method
GET

### Endpoint
/policy-management/cloud-gateway/v1/anti-spoofing-bypass/policies
```

--------------------------------

### GET /policy-management/cloud-gateway/v1/delivery-route/definitions

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves a list of delivery route definitions.

```APIDOC
## GET /policy-management/cloud-gateway/v1/delivery-route/definitions

### Description
Retrieves a list of delivery route definitions.

### Method
GET

### Endpoint
/policy-management/cloud-gateway/v1/delivery-route/definitions

```

--------------------------------

### Invoke-MimecastApi

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/powershell-basic.ps1.md

Documentation for the Invoke-MimecastApi PowerShell function, including parameters, return type, and examples.

```APIDOC
## Invoke-MimecastApi

### Description
Invokes the Mimecast API with the provided base URL, bearer token, HTTP method, path, and optional request body. It serializes the body to JSON (capped at depth 6) and retries the request according to the retry policy of Invoke-WithRetry.

### Method
N/A (PowerShell function)

### Endpoint
N/A (PowerShell function)

### Parameters
- **BaseUrl** (string) - Required - Tenant base URL (e.g. `https://api.services.mimecast.com`)
- **Token** (string) - Required - Bearer token
- **Method** (string) - Required - HTTP method; pass `$endpoint.method`
- **Path** (string) - Required - Endpoint path; pass `$endpoint.path`
- **Body** (hashtable) - Optional - Request body; an empty hashtable sends no body (default `@{}`)

### Request Example
```powershell
$response = Invoke-MimecastApi -BaseUrl $creds.BaseUrl -Token $token -Method $endpoint.method -Path $endpoint.path -Body $body
$response | ConvertTo-Json -Depth 6
```

### Response
#### Success Response
Returns the `Invoke-RestMethod` response object (JSON-decoded), or `$null` for 204-type responses.

#### Response Example
```powershell
$response | ConvertTo-Json -Depth 6
```

### Error Handling
Throws `Invoke-RestMethod`'s HTTP error exception, subject to the retry policy of `Invoke-WithRetry`. Note: `$Body | ConvertTo-Json -Depth 6` caps nesting at depth 6 — deeper payloads are truncated.

#### Error Example
```powershell
try {
    $response = Invoke-MimecastApi -BaseUrl $creds.BaseUrl -Token $token -Method "POST" -Path "/api/user/create-user" -Body @{ data = @(@{ emailAddress = "user@example.com" }) }
} catch {
    Write-Error "API call failed: $($_.Exception.Message)"
}
```
```

--------------------------------

### GET /policy-management/cloud-gateway/v1/delivery-route/definitions

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves a list of delivery route definitions.

```APIDOC
## GET /policy-management/cloud-gateway/v1/delivery-route/definitions

### Description
Retrieves a list of delivery route definitions.

### Method
GET

### Endpoint
/policy-management/cloud-gateway/v1/delivery-route/definitions
```

--------------------------------

### Define script parameters for PowerShell module

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/powershell-basic.ps1.md

Defines the script parameters with default values for the PowerShell example. Paths are resolved relative to the current directory, script directory, and parent directory. $ErrorActionPreference is set to 'Stop' so command errors throw.

```powershell
param(
    [string]$ApiRefPath = "../api-reference.json",
    [string]$CredsPath = "../credentials.json",
    [string]$TargetMethod = "GET",
    [string]$TargetPath = "/account/cloud-gateway/v1/emergency-contact"
)
```

--------------------------------

### Parameter object example for get-audit-events

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/types.md

Example of a Parameter object from the get-audit-events endpoint. The name field includes the '(required)' suffix and the description begins with the JSON type 'string'.

```json
{
  "name": "endDateTime (required)",
  "description": "string (yyyy-MM-dd'T'HH:mm:ssZ) The end date in ISO 8601 date time format (e.g. 2011-12-03T10:15:30+0000)."
}
```

--------------------------------

### Get-Endpoint

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/powershell-basic.ps1.md

Documentation for the Get-Endpoint PowerShell function, including signature, parameters, return type, errors, and usage examples.

```APIDOC
## Get-Endpoint

### Description
Retrieves an endpoint definition from the API reference file by matching the exact path and method. Throws an error if the reference file cannot be found or if no matching endpoint exists.

### Method
Function

### Signature
```powershell
function Get-Endpoint {
    param([string]$ApiPath, [string]$Method, [string]$JsonPath)
    $resolvedPath = Resolve-ApiReferencePath $JsonPath
    if (!$resolvedPath) { throw "API reference file not found. Tried: $JsonPath, and local directories." }
    $data = Get-Content $resolvedPath | ConvertFrom-Json
    $match = $data.endpoints | Where-Object { $_.path -eq $ApiPath -and $_.method -eq $Method } | Select-Object -First 1
    if (-not $match) { throw "Endpoint not found for $Method $ApiPath" }
    return $match
}
```

### Parameters
- **ApiPath** (string) - Required - Exact endpoint path to match
- **Method** (string) - Required - Exact endpoint method to match
- **JsonPath** (string) - Required - Suggested path to api-reference.json

### Return Value
PowerShell object - The first Endpoint object with matching path and method; usable as $endpoint.method, $endpoint.path, $endpoint.parameters, etc.

### Errors
- Throws string "API reference file not found. Tried: $JsonPath, and local directories." when the reference file cannot be resolved
- Throws string "Endpoint not found for $Method $ApiPath" when no endpoint matches

### Examples
Basic call:
```powershell
$endpoint = Get-Endpoint -ApiPath "/api/user/get-internal-users" -Method "POST" -JsonPath $ApiRefPath
```

Error handling:
```powershell
try {
    $endpoint = Get-Endpoint -ApiPath $TargetPath -Method $TargetMethod -JsonPath $ApiRefPath
} catch {
    Write-Error "Endpoint lookup failed: $_"
    exit 1
}
```
```

--------------------------------

### Basic GET call to emergency-contact endpoint

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/python-basic.py.md

Basic GET call to the emergency-contact endpoint. Passes the tenant BaseUrl from credentials.json and the OAuth2 token; prints the JSON-decoded response with indentation.

```python
result = call_mimecast(creds["BaseUrl"], token, "GET",
                       "/account/cloud-gateway/v1/emergency-contact")
print(json.dumps(result, indent=2))
```

--------------------------------

### main() function definition from examples/python-basic.py

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/python-basic.py.md

This function loads credentials and endpoint configuration, obtains a Mimecast token, makes the API call, and prints the JSON response. It returns None and may raise exceptions from the called helpers, such as SystemExit when TARGET_PATH or TARGET_METHOD is not in the reference.

```python
def main():
    creds = load_credentials(CREDS_PATH)
    endpoint = load_endpoint(TARGET_PATH, TARGET_METHOD, API_REF_PATH)

    token = get_mimecast_token(creds["BaseUrl"], creds["ClientId"], creds["ClientSecret"]) 

    body = {}
    result = call_mimecast(creds["BaseUrl"], token, endpoint["method"], endpoint["path"], body)
    print(json.dumps(result, indent=2))
```

--------------------------------

### Error-handling example for score_endpoint

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/find_endpoint.py.md

Shows that terms are not lower-cased inside score_endpoint; the caller must normalize case. Demonstrates scoring with a single term (0) and two terms (10).

```python
from find_endpoint import score_endpoint

endpoint = {"name": "Get Internal Users", "path": "/api/user/get-internal-users",
            "category": "User and Group Management", "method": "POST",
            "description": "Returns internal users"}
# caller must normalize case, otherwise "internal" is still a substring
print(score_endpoint(endpoint, ["internalusers"]))   # 0 - no substring match
print(score_endpoint(endpoint, ["internal", "users"]))  # 10 - (3+2) per term
```

--------------------------------

### GET /threats/v1/stats/unwanted

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves unwanted statistics.

```APIDOC
## GET /threats/v1/stats/unwanted

### Description
Retrieves unwanted statistics.

### Method
GET

### Endpoint
/threats/v1/stats/unwanted

```

--------------------------------

### Bulk action with filtering (Python)

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/PROMPTS.md

Use this prompt to generate a Python script that retrieves items from an endpoint, authenticates with client credentials, paginates, filters records, and outputs a CSV with specified fields.

```text
From `api-reference.json`, identify the endpoint that retrieves [items]. Generate a Python script that:
- Authenticates using client credentials from `credentials.json`
- Paginates if needed
- Filters for records where [condition]
- Outputs CSV with fields A,B,C
```

--------------------------------

### call_mimecast: authenticated Mimecast API request with retry

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/python-basic.py.md

Core helper that builds the request URL and headers, performs the HTTP call via requests, raises on HTTP errors, and wraps the call in invoke_with_retry. The retry policy handles 429/500/502/503/504 with up to 4 attempts and exponential backoff starting at 0.5 s.

```python
def call_mimecast(base_url: str, token: str, method: str, path: str, body: dict | None = None):
    url = f"{base_url}{path}"
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    }
    def do_call():
        resp = requests.request(method, url, headers=headers, json=body)
        resp.raise_for_status()
        return resp.json()
    return invoke_with_retry(do_call)
```

--------------------------------

### GET /threats/v1/stats/suspicious

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves suspicious statistics.

```APIDOC
## GET /threats/v1/stats/suspicious

### Description
Retrieves suspicious statistics.

### Method
GET

### Endpoint
/threats/v1/stats/suspicious

```

--------------------------------

### GET /threats/v1/stats/phishing

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves phishing statistics.

```APIDOC
## GET /threats/v1/stats/phishing

### Description
Retrieves phishing statistics.

### Method
GET

### Endpoint
/threats/v1/stats/phishing

```

--------------------------------

### main() function signature

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/find_endpoint.py.md

Defines the command-line interface for the endpoint search script. Sets up argparse with a positional query argument and optional flags for API reference path, category filter, and result limit.

```python
def main():
    p = argparse.ArgumentParser(description="Search Mimecast API endpoints by keywords")
    p.add_argument("query", nargs="+", help="Keywords to search for (e.g. blocked senders list)")
    p.add_argument("--api-ref", default="api-reference.json", help="Path to api-reference.json")
    p.add_argument("--category", help="Filter by category name (optional)")
    p.add_argument("--limit", type=int, default=10, help="Number of results to show")
    args = p.parse_args()
```

--------------------------------

### POST /directory/cloud-gateway/v1/integrations/m365

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Creates a new M365 integration.

```APIDOC
## POST /directory/cloud-gateway/v1/integrations/m365

### Description
Creates a new M365 integration.

### Method
POST

### Endpoint
/directory/cloud-gateway/v1/integrations/m365
```

--------------------------------

### GET /threats/v1/stats/impersonations

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves impersonation statistics.

```APIDOC
## GET /threats/v1/stats/impersonations

### Description
Retrieves impersonation statistics.

### Method
GET

### Endpoint
/threats/v1/stats/impersonations

```

--------------------------------

### POST /directory/cloud-gateway/v1/integrations/google

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Creates a new Google integration.

```APIDOC
## POST /directory/cloud-gateway/v1/integrations/google

### Description
Creates a new Google integration.

### Method
POST

### Endpoint
/directory/cloud-gateway/v1/integrations/google
```

--------------------------------

### GET /threats/v1/events

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves threat events.

```APIDOC
## GET /threats/v1/events

### Description
Retrieves threat events.

### Method
GET

### Endpoint
/threats/v1/events

```

--------------------------------

### GET /threat-reporting/v1/threat-reports

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves threat reports.

```APIDOC
## GET /threat-reporting/v1/threat-reports

### Description
Retrieves threat reports.

### Method
GET

### Endpoint
/threat-reporting/v1/threat-reports

```

--------------------------------

### Basic usage of load_credentials

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/python-basic.py.md

Calls load_credentials with a credentials filename and prints the BaseUrl. Assumes credentials.json is present at the given path.

```python
from python_basic import load_credentials

creds = load_credentials("credentials.json")
print(creds["BaseUrl"])   # https://api.services.mimecast.com
```

--------------------------------

### GET /threat-reporting/v1/reported-emails

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves reported emails.

```APIDOC
## GET /threat-reporting/v1/reported-emails

### Description
Retrieves reported emails.

### Method
GET

### Endpoint
/threat-reporting/v1/reported-emails

```

--------------------------------

### GET /user/cloud-gateway/v1/users

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves a list of users.

```APIDOC
## GET /user/cloud-gateway/v1/users

### Description
Retrieves a list of users.

### Method
GET

### Endpoint
/user/cloud-gateway/v1/users
```

--------------------------------

### POST /api/policy/webwhiteurl/create-policy-with-targets

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Creates a web white URL policy with targets.

```APIDOC
## POST /api/policy/webwhiteurl/create-policy-with-targets

### Description
Creates a web white URL policy with targets.

### Method
POST

### Endpoint
/api/policy/webwhiteurl/create-policy-with-targets

```

--------------------------------

### GET /email/cloud-gateway/v1/statistics

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves email statistics.

```APIDOC
## GET /email/cloud-gateway/v1/statistics

### Description
Retrieves email statistics.

### Method
GET

### Endpoint
/email/cloud-gateway/v1/statistics
```

--------------------------------

### Expected output shape

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/find_endpoint.py.md

Shows the format of the printed results: category, method, path, name, truncated description, parameter count, and documentation URL.

```text
[Audit Events] POST /api/audit/get-audit-events  -- Get Audit Events
  desc: Description Returns the audit events matching the request. Returns the au...
  params: 10
  url: https://developer.services.mimecast.com/docs/auditevents/1/routes/api/audit/get-audit-events/post
```

--------------------------------

### GET /threats/v1/stats/url-clicks

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves URL click statistics.

```APIDOC
## GET /threats/v1/stats/url-clicks

### Description
Retrieves URL click statistics.

### Method
GET

### Endpoint
/threats/v1/stats/url-clicks

```

--------------------------------

### GET /threats/v1/stats/threats-by-sender

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves threat statistics by sender.

```APIDOC
## GET /threats/v1/stats/threats-by-sender

### Description
Retrieves threat statistics by sender.

### Method
GET

### Endpoint
/threats/v1/stats/threats-by-sender

```

--------------------------------

### POST /directory/cloud-gateway/v1/integrations/active-directory

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Creates a new Active Directory integration.

```APIDOC
## POST /directory/cloud-gateway/v1/integrations/active-directory

### Description
Creates a new Active Directory integration.

### Method
POST

### Endpoint
/directory/cloud-gateway/v1/integrations/active-directory
```

--------------------------------

### GET /threats/v1/stats/threats-by-recipient

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves threat statistics by recipient.

```APIDOC
## GET /threats/v1/stats/threats-by-recipient

### Description
Retrieves threat statistics by recipient.

### Method
GET

### Endpoint
/threats/v1/stats/threats-by-recipient

```

--------------------------------

### credentials.json.template - API credentials file

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/configuration.md

Template for the credentials.json file. Contains the BaseUrl, ClientId, and ClientSecret keys required by the Mimecast API. The real file is git-ignored and never committed.

```json
{
  "BaseUrl": "https://api.services.mimecast.com",
  "ClientId": "YOUR_CLIENT_ID_HERE",
  "ClientSecret": "YOUR_CLIENT_SECRET_HERE"
}
```

--------------------------------

### Generate New VS Code Workspace

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/README.md

Paste this prompt into your AI assistant inside VS Code to generate and open a new workspace named Mimecast-API-Action-Pack at ~/dev, cloning the source repository. The assistant should stop once the workspace is open.

```text
Create and open a new VS Code workspace.
Workspace details:
- Name: Mimecast-API-Action-Pack
- Location: ~/dev
- Source repository:
  https://github.com/ecpunk/Mimecast-API-Action-Pack
Rules:
- Create ~/dev if it does not exist
- Open the workspace immediately
- Use VS Code's native workspace generation flow
- Stop once the workspace is open
```

--------------------------------

### load_credentials(path: str) -> dict

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/python-basic.py.md

Loads and parses a credentials JSON file from the given filesystem path. Returns the parsed credentials object with expected keys BaseUrl, ClientId, and ClientSecret.

```APIDOC
## load_credentials(path: str) -> dict

### Description
Loads and parses a credentials JSON file from the given filesystem path. Returns the parsed credentials object with expected keys BaseUrl, ClientId, and ClientSecret.

### Method
Function

### Signature
```python
def load_credentials(path: str) -> dict:
    with open(path) as f:
        return json.load(f)
```

### Parameters
- **path** (str) - Required - Filesystem path to credentials.json

### Returns
- **dict** - The parsed credentials object. Expected keys: BaseUrl, ClientId, ClientSecret.

### Exceptions
- FileNotFoundError - Propagates to caller if file not found.
- json.JSONDecodeError - Propagates to caller if JSON is invalid.
- PermissionError - Propagates to caller if file is unreadable.

### Example
```python
from python_basic import load_credentials

creds = load_credentials("credentials.json")
print(creds["BaseUrl"])   # https://api.services.mimecast.com
```
```

--------------------------------

### GET /threats/v1/stats/attachment-scans

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves attachment scan statistics.

```APIDOC
## GET /threats/v1/stats/attachment-scans

### Description
Retrieves attachment scan statistics.

### Method
GET

### Endpoint
/threats/v1/stats/attachment-scans

```

--------------------------------

### Nontrivial usage with category filter and custom API reference path

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/find_endpoint.py.md

Demonstrates using the --api-ref and --category options together to search within a specific category and a non-default reference file.

```bash
python tools/find_endpoint.py audit categories --api-ref ./data/api-reference.json --category "Audit Events"
```

--------------------------------

### GET /threat-reporting/v1/subscriptions

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves threat reporting subscriptions.

```APIDOC
## GET /threat-reporting/v1/subscriptions

### Description
Retrieves threat reporting subscriptions.

### Method
GET

### Endpoint
/threat-reporting/v1/subscriptions

```

--------------------------------

### POST /api/byo-threat-intelligence/create-batch

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Creates a batch of threat intelligence data.

```APIDOC
## POST /api/byo-threat-intelligence/create-batch

### Description
Creates a batch of threat intelligence data.

### Method
POST

### Endpoint
/api/byo-threat-intelligence/create-batch

```

--------------------------------

### GET /email/cloud-gateway/v1/outbound-ip-addresses

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves outbound IP addresses.

```APIDOC
## GET /email/cloud-gateway/v1/outbound-ip-addresses

### Description
Retrieves outbound IP addresses.

### Method
GET

### Endpoint
/email/cloud-gateway/v1/outbound-ip-addresses
```

--------------------------------

### GET /email/cloud-gateway/v1/gateway-details

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves email gateway details.

```APIDOC
## GET /email/cloud-gateway/v1/gateway-details

### Description
Retrieves email gateway details.

### Method
GET

### Endpoint
/email/cloud-gateway/v1/gateway-details
```

--------------------------------

### POST /connector/cloud-gateway/v1/connectors

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Creates a new connector.

```APIDOC
## POST /connector/cloud-gateway/v1/connectors

### Description
Creates a new connector.

### Method
POST

### Endpoint
/connector/cloud-gateway/v1/connectors
```

--------------------------------

### Error handling for missing credentials file

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/python-basic.py.md

Catches FileNotFoundError when loading credentials and exits with a message instructing to copy credentials.json.template to credentials.json.

```python
try:
    creds = load_credentials(CREDS_PATH)
except FileNotFoundError:
    raise SystemExit("Copy credentials.json.template to credentials.json first")
```

--------------------------------

### GET /domain/cloud-gateway/v1/pending-domains

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves a list of pending domains.

```APIDOC
## GET /domain/cloud-gateway/v1/pending-domains

### Description
Retrieves a list of pending domains.

### Method
GET

### Endpoint
/domain/cloud-gateway/v1/pending-domains
```

--------------------------------

### GET /domain/cloud-gateway/v1/internal-domains

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves a list of internal domains.

```APIDOC
## GET /domain/cloud-gateway/v1/internal-domains

### Description
Retrieves a list of internal domains.

### Method
GET

### Endpoint
/domain/cloud-gateway/v1/internal-domains
```

--------------------------------

### Basic call to load_endpoints

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/find_endpoint.py.md

Shows the minimal usage of load_endpoints with a Path to 'api-reference.json'. Note that the import of find_endpoint is expected to be available in the same directory or Python path.

```python
from pathlib import Path
from find_endpoint import load_endpoints

endpoints = load_endpoints(Path("api-reference.json"))
print(f"{len(endpoints)} endpoints loaded")
```

--------------------------------

### GET /domain/cloud-gateway/v1/external-domains

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves a list of external domains.

```APIDOC
## GET /domain/cloud-gateway/v1/external-domains

### Description
Retrieves a list of external domains.

### Method
GET

### Endpoint
/domain/cloud-gateway/v1/external-domains
```

--------------------------------

### POST /policy-management/cloud-gateway/v1/anti-spoofing-bypass/policies

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Creates an anti-spoofing bypass policy.

```APIDOC
## POST /policy-management/cloud-gateway/v1/anti-spoofing-bypass/policies

### Description
Creates an anti-spoofing bypass policy.

### Method
POST

### Endpoint
/policy-management/cloud-gateway/v1/anti-spoofing-bypass/policies

```

--------------------------------

### GET /directory/cloud-gateway/v1/groups

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves a list of directory groups.

```APIDOC
## GET /directory/cloud-gateway/v1/groups

### Description
Retrieves a list of directory groups.

### Method
GET

### Endpoint
/directory/cloud-gateway/v1/groups
```

--------------------------------

### POST /domain/cloud-gateway/v1/pending-domains

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Creates a new pending domain.

```APIDOC
## POST /domain/cloud-gateway/v1/pending-domains

### Description
Creates a new pending domain.

### Method
POST

### Endpoint
/domain/cloud-gateway/v1/pending-domains
```

--------------------------------

### GET /account/cloud-gateway/v1/emergency-contact

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves the emergency contact information.

```APIDOC
## GET /account/cloud-gateway/v1/emergency-contact

### Description
Retrieves the emergency contact information.

### Method
GET

### Endpoint
/account/cloud-gateway/v1/emergency-contact
```

--------------------------------

### Transform and enrich

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/PROMPTS.md

Use this prompt to generate a PowerShell script that calls an endpoint, deduplicates results by a key, outputs top 10 domains, and includes retries and basic logging.

```text
Create a PowerShell script that calls `<METHOD> <PATH>`, deduplicates results by `<key>`, and outputs top 10 domains. Include retries and basic logging.
```

--------------------------------

### GET /threat-reporting/v1/threat-analysis/{threatAnalysisId}

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves a threat analysis by ID.

```APIDOC
## GET /threat-reporting/v1/threat-analysis/{threatAnalysisId}

### Description
Retrieves a threat analysis by ID.

### Method
GET

### Endpoint
/threat-reporting/v1/threat-analysis/{threatAnalysisId}

### Parameters
#### Path Parameters
- **threatAnalysisId** (string) - Required - The ID of the threat analysis.

```

--------------------------------

### GET /siem/v1/events/cg

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/endpoints.md

Retrieves SIEM events for Cloud Gateway.

```APIDOC
## GET /siem/v1/events/cg

### Description
Retrieves SIEM events for Cloud Gateway.

### Method
GET

### Endpoint
/siem/v1/events/cg

```

--------------------------------

### load_endpoint(api_path: str, method: str, json_path: str) -> dict

Source: https://github.com/ecpunk/mimecast-api-action-pack/blob/main/_autodocs/api-reference/python-basic.py.md

Loads an endpoint definition from a JSON file by matching the given path and method. Returns the first matching endpoint object or raises SystemExit if not found.

```APIDOC
## load_endpoint(api_path: str, method: str, json_path: str) -> dict

### Description
Loads an endpoint definition from a JSON file by matching the given path and method. Returns the first matching endpoint object or raises SystemExit if not found.

### Method
Function call

### Endpoint
N/A (Python function)

### Parameters
- **api_path** (str) - Required - Exact endpoint `path` to match, e.g. `/account/cloud-gateway/v1/emergency-contact`
- **method** (str) - Required - Exact endpoint `method` to match, e.g. `"GET"`
- **json_path** (str) - Required - Filesystem path to `api-reference.json`

### Return Type
`dict` - The first [Endpoint object](../types.md#endpoint) whose `path` and `method` match both arguments; returns the first hit (iteration order is the file's array order).

### Exceptions
- **SystemExit** - Raised with message `Endpoint not found for {method} {api_path}` when no endpoint matches.
- **FileNotFoundError** - Propagates if the JSON file does not exist.
- **json.JSONDecodeError** - Propagates if the JSON file is invalid.

### Request Example
N/A (function call)

### Response
#### Success Response
Returns a dictionary representing the endpoint object.

#### Response Example
N/A (function call)

### Error Handling
- If no endpoint matches, `SystemExit` is raised with message `Endpoint not found for {method} {api_path}`.
- File-related errors propagate as-is.

### Usage Examples

Basic call:

python
from python_basic import load_endpoint, API_REF_PATH

ep = load_endpoint("/api/account/get-account", "POST", API_REF_PATH)
print(ep["id"], ep["url"])


Error handling:

python
try:
    load_endpoint("/does/not/exist", "GET", API_REF_PATH)
except SystemExit as exc:
    print(f"lookup failed: {exc}")

```