Salesforce integration

PostBuddy ships an unlocked Salesforce package: a Flow Builder action that sends mail items, a Mail Item object that mirrors their status, and a status writeback through our webhooks (or polling of the events endpoint).

#Install

1. In the portal, open Integrations and install Salesforce. Fill in the instance URL, choose the writeback method and copy the dedicated API key and, with a writeback, the webhook secret; both are shown once.
2. Install the package in your org from the install URL in the release notes, or deploy the source from apps/salesforce with the Salesforce CLI.
3. Assign the permission sets: PostBuddy Admin to the person who configures the connection, PostBuddy User to everyone whose flows send mail.
4. In Setup, Named Credentials, open the external credential PostBuddy API, add a principal named PostBuddy with the parameter ApiKey set to the dedicated live key, and grant it to the permission sets. Repeat for PostBuddy API (test) with a test key when you want to try flows without printing anything.
5. Check the API URL. The package ships both Named Credentials, PostBuddy API and PostBuddy API (test), with the production API https://api.postbuddy.nl. For another environment, in Setup, Named Credentials, edit both and set the URL to that environment's API base URL: the address your API keys call (https://api.postbuddy.nl), without a trailing slash and without /v1. Then run both connection tests on the PostBuddy Setup tab.
6. Open the PostBuddy Setup tab: paste the webhook secret, run the connection tests and, in a sandbox, keep the test mode default on. The page warns when a sandbox would send live mail.

#Send mail from a flow

Add the action "Send Mail Item" (category PostBuddy) to a record-triggered or scheduled flow:

Outputs: is success, item id, status, warnings, error code and message, and the Mail Item record id. The action is bulkified up to 100 records per transaction; larger batches answer batch_too_large.

#Status writeback

With a writeback configured, PostBuddy delivers item.* events for the items created from Salesforce to https://<my domain>/services/apexrest/postbuddy/webhook. The Apex resource verifies the signature with the secret from the settings, updates the Mail Item (status, last event, completed at) and publishes the platform event PostBuddy_Item_Event__e so your own flows and triggers can react. Without a writeback, schedule PostBuddyPollEventsJob every 15 minutes; it walks GET /v1/events forward from its stored position in time windows and applies item events oldest first, through the credential of the installation's mode (test in a sandbox unless live is allowed).

Choose "Mirror every item" on the installation when the Mail Item object should also show items created outside Salesforce.

#Authenticating the writeback

The Apex resource lives behind Salesforce authentication, so PostBuddy needs a way in. Two methods are supported on the installation:

• Connected App (recommended). In Setup, App Manager, create a Connected App with OAuth enabled, the scopes api and refresh_token, offline_access, and under "Manage", edit the policies to enable the client credentials flow with a run-as user that holds the PostBuddy Admin permission set. Copy the consumer key and secret into the installation as the client id and client secret. PostBuddy obtains a token from https://<instance>/services/oauth2/token before a delivery (cached and refreshed on a 401) and sends it as Authorization: Bearer, next to the signature.
• Site guest. Expose the resource through a Site or Experience Cloud site with a guest user that holds the Apex class access and the object permissions. Only the signature protects the endpoint; prefer the Connected App.

Both methods verify every delivery with the webhook secret; rotate it from the portal and paste the new value on the setup page.