BulkForge
Customer Install Guide

What is the Agent?

A .NET 10 Azure Functions app (Linux Flex Consumption) that runs in your subscription. It polls the BulkForge control plane for outbound jobs, reads delivery credentials from your Key Vault via managed identity, sends through Postmark and/or ACS, and reports per-recipient audit results back over HTTPS. Your tokens never leave your tenant.

Prerequisites

• Active BulkForge SaaS subscription — subscribe via Azure Marketplace, complete onboarding at the control plane, and create an agent in Manage Agents to obtain your Agent ID and Agent Key.
• Azure subscription with permission to create resource groups, Function Apps (Flex Consumption), Storage accounts, and Key Vaults.
• At least one delivery channel:
  • Postmark — Server API token (Servers → API Tokens). Optional: Account token (sender/template sync in dashboard).
  • Azure Communication Services (optional) — connection string and verified sender address from your ACS resource.
• Agent Package URL — public HTTPS zip (default in the Marketplace wizard; override only when pinned to a specific release).

Channel priority, fallback routing, and default From addresses are configured in the BulkForge dashboard under Manage Agents after install — not in the Marketplace wizard.

Install via Azure Marketplace

1. Subscribe to BulkForge SaaS on Azure Marketplace and complete control-plane onboarding.
2. In Azure Portal, open the BulkForge Install offer (Azure Application) and click Create.
3. Basics — subscription, region, resource group (e.g. rg-bulkforge-agent).
4. Agent Configuration — provide Postmark and/or ACS credentials (at least one channel required):
   • Postmark Server Token (optional if using ACS)
   • Postmark Account Token (optional)
   • ACS Connection String (optional)
   • ACS sender email address (optional)
5. Control Plane Connection — paste Agent ID and Agent Key from Manage Agents. Control plane URL is set automatically to https://bulkforge-engine-prod.azurewebsites.net.
6. Review + create → wait approximately 3–5 minutes.

The template provisions:

• Function App (agent-<random>) on Linux Flex Consumption (.NET 10 isolated via functionAppConfig).
• Storage account — runtime and deployment package container.
• Key Vault — Postmark tokens, ACS connection string, and sender address (RBAC; Function App reads via managed identity).
• A deployment script that copies the agent zip from the package URL into deployments/released-package.zip (no WEBSITE_RUN_FROM_PACKAGE on Flex).

Metadata sync: After start, MetadataSyncFunction runs immediately, then every 15 minutes, pushing Postmark templates and sender signatures to the dashboard when tokens are configured. If the From Address dropdown is empty right after install, wait one sync cycle or restart the Function App.

After Deployment

1. Open the Function App (name starts with agent-) and confirm AgentPollingFunction is running — first poll within ~1 minute.
2. In the BulkForge dashboard, open Manage Agents. Your agent should show Status: Active with a recent lastHeartbeat.
3. Configure delivery channel priority and defaults under Manage Agents if using both Postmark and ACS.
4. Compose a campaign, upload recipients, or trigger a workflow via the API / Power Automate connector.

Verifying the Install

• Dashboard → Manage Agents → agent status Active with current heartbeat
• Submit a small test campaign and confirm per-recipient delivery results in the job audit view
• Function App → Log stream — no repeated HTTP 401/403 against the control plane URL
• Key Vault → Function App managed identity has Key Vault Secrets User

Troubleshooting

Agent does not go Active (within ~5 minutes)

Check Function App Log stream for HTTP errors against the control plane. Common causes: wrong Agent ID, mismatched Agent Key, or inactive SaaS subscription. Confirm Function App → Identity → system-assigned is On and Key Vault RBAC grants Key Vault Secrets User.

Functions blade empty

Wait 2–3 minutes. Confirm released-package.zip exists in the deployments container. Restart the Function App once. For manual recovery, run OneDeploy with a public package URL (use a JSON file; inline --body breaks):

@'
{"properties":{"packageUri":"https://YOUR-RELEASES-BLOB/customer-agent-code.zip","remoteBuild":false}}
'@ | Set-Content -Encoding utf8 onedeploy-body.json

$sub = az account show --query id -o tsv
$uri = "https://management.azure.com/subscriptions/$sub/resourceGroups/YOUR_RG/providers/Microsoft.Web/sites/YOUR_FUNCTION_APP/extensions/onedeploy?api-version=2022-09-01"
az rest --method PUT --uri $uri --headers "Content-Type=application/json" --body "@onedeploy-body.json"

Runtime / stack errors

Use Flex Consumption (FC1). Runtime is functionAppConfig → dotnet-isolated 10.0 — do not change legacy Stack settings in the portal. If deployment fails with an FC1 SKU error, pick a supported region.

ACS sends fail

Verify ACS connection string and sender address in Key Vault match a verified ACS domain. Confirm channel routing in Manage Agents selects ACS for the job.

Updating the Agent

We publish builds to public Azure Blob Storage (customer-agent-code.zip tracks latest; versioned names are also available). Upload the new zip to deployments/released-package.zip or run OneDeploy, then restart the Function App. You do not need to redeploy the full ARM template for routine code updates.

Rotating Secrets

Postmark or ACS credentials

1. Key Vault → relevant secret → New version → paste updated value.
2. Restart the Function App.

Agent Key

1. Dashboard → Manage Agents → Regenerate key.
2. Function App → Configuration → AGENT_KEY → save (app recycles automatically).

Data and Privacy

Delivery credentials are stored in your Key Vault; we never see them. The control plane stores campaign metadata, recipient counts, delivery status summaries, and audit records — not full recipient lists or message bodies. Those are dispatched from your agent directly to Postmark or ACS. All agent ↔ control plane traffic is HTTPS.

Uninstall

Delete the agent resource group:

az group delete --name rg-bulkforge-agent --yes

Your control-plane subscription and historical job audit data remain unless you request engine record removal from support.

Support

Email support@ageebgeesolutions.com. Include Agent ID, resource group, region, delivery channel (Postmark/ACS), and Function App Log stream lines (UTC).

Product overview: What is BulkForge? · Architecture: Reference architecture