Manage Destinations and Output Settings

Destinations control where PBRS sends a report and which output format it generates. A single-report schedule can include email destinations, disk destinations, or both.

For a complete PowerShell example, follow Update Email Recipients Without Changing Other Destination Settings. The recipe updates To recipients, preserves other destination settings, and verifies the saved changes without executing the schedule.

Use the dedicated email destination endpoints to add an email destination, update its recipients or message, or delete it. To manage disk destinations or change other output settings, update the complete schedule definition.

Before you begin

You need:

• A running PBRS API service.
• A valid access token.
• The uniqueid of the schedule you want to manage.
• Access to the schedule’s current configuration.

Send your access token with each request:

Authorization: Bearer YOUR_ACCESS_TOKEN

For requests with a JSON body, also send:

Content-Type: application/json

Schedule IDs and destination IDs identify different objects:

Read the existing destinations

Retrieve the schedule before changing its destinations. Use the endpoint that matches the report source.

Inspect the EmailDestinations and DiskDestinations collections. Record the DestinationId of each destination you intend to change or retain.

Do not assume the retrieved response is a complete, reusable update request. Some settings may be omitted or returned in a form that cannot be submitted unchanged. Keep an authoritative copy of the schedule configuration, including any required export settings and credentials.

Email destination operations

These operations apply to single-report schedules. Do not substitute package IDs for single-report schedule IDs.

Add an email destination

Send a JSON request containing the parent schedule ID and at least one recipient in To.

POST /api/SingleSchedule/AddEmailDestination?clearExisting=false

{
  "ParentId": 101,
  "DestinationName": "Operations email",
  "DestinationType": "Email",
  "Enabled": true,
  "OutputFormat": "Acrobat Format (*.pdf)",
  "To": [
    "[email protected]"
  ],
  "Cc": [],
  "Bcc": [],
  "Subject": "Daily sales report",
  "Body": "Attached is the daily sales report.",
  "BodyFormat": "TEXT",
  "EmbedReport": false
}

Replace 101 with the schedule’s uniqueid and replace the example address with the intended recipient.

A successful request returns HTTP 200 with the new destination ID:

{
  "DestinationId": 701
}

Save this ID for later updates or deletion.

Preserve or replace existing email destinations

The optional clearExisting query parameter defaults to false.

clearExisting=true does not remove disk destinations or other destination types.

Use clearExisting=true only when you intend to replace every existing email destination. Existing email destinations are deleted before the new one is added; do not assume they will be restored if the addition fails.

Recipient fields

Provide recipients as JSON arrays.

{
  "To": [
    "[email protected]",
    "[email protected]"
  ],
  "Cc": [
    "[email protected]"
  ],
  "Bcc": []
}

Do not submit multiple addresses as one comma-separated string.

Update an email destination

Use the dedicated update endpoint to change recipients, subject, body, body format, or sender fields.

PUT /api/SingleSchedule/UpdateEmailDestination

This operation requires the existing DestinationId. It does not accept a complete email destination definition.

Preserve fields when making a selective update

The endpoint treats empty arrays, null, and omitted fields differently.

Omitting Cc or Bcc can clear those recipients because their default is an empty array. Omitting BodyFormat can change an existing HTML body to text because its default is TEXT.

Use explicit JSON null values when preserving these fields.

Change only the subject

{
  "DestinationId": 701,
  "To": null,
  "Cc": null,
  "Bcc": null,
  "Subject": "Updated daily sales report",
  "Body": null,
  "BodyFormat": null,
  "CustomSenderName": null,
  "CustomerSenderAddress": null
}

A successful request returns HTTP 200:

{
  "Message": "Email destination updated successfully",
  "DestinationId": 701
}

Replace recipients and clear CC recipients

This example replaces To, clears Cc, and preserves Bcc and the existing body format.

{
  "DestinationId": 701,
  "To": [
    "[email protected]"
  ],
  "Cc": [],
  "Bcc": null,
  "BodyFormat": null
}

An empty To array does not clear the primary recipients. Similarly, an empty string does not clear the subject, body, or sender fields.

Settings that require a full schedule update

The dedicated email update endpoint does not change:

• Destination name.
• Destination enabled state.
• Output format.
• Custom output filename or extension.
• Report embedding settings.
• Power BI data-only Excel export settings.

To change these settings, use the appropriate full schedule update endpoint.

The selective-update rules above apply only to UpdateEmailDestination. Do not apply them to destination collections in a full schedule update.

Delete an email destination

First retrieve the parent schedule and confirm that the destination ID belongs to the destination you intend to remove.

Then send:

DELETE /api/SingleSchedule/DeleteEmailDestination?destinationId=701

Use the query parameter destinationId. Do not send a request body.

A successful request returns HTTP 200:

{
  "Message": "Email destination deleted successfully",
  "DestinationId": 701
}

Retrieve the parent schedule again to verify that the destination was removed and the destinations you intended to retain are still present.

Deleting a destination does not recall output that has already been delivered. Do not rely on deletion to cancel an execution already in progress.

Choose the output format

Set OutputFormat on the destination using the exact format name supported by the report source.

Output support depends on the report source and export configuration. Do not assume that a format available for one source is available for every source.

For Power BI data-only Excel exports, provide a nonempty PowerBIDataOnlyExportSettings collection containing the required export configuration.

See Export Power BI Visual Data to Excel for the export settings and examples.

Custom filenames and extensions

Destinations can include:

Leave these fields at their defaults unless you need to override the generated name.

Changing the extension does not change the generated file format. Select the format through OutputFormat.

Configure the email message

Text and HTML bodies

Use BodyFormat to specify how PBRS interprets Body.

For example:

{
  "DestinationId": 701,
  "To": null,
  "Cc": null,
  "Bcc": null,
  "Subject": "Daily sales report",
  "Body": "<p>Hello,</p><p>Your daily sales report is attached.</p>",
  "BodyFormat": "HTML"
}

Use a JSON serializer when building requests programmatically so that quotes, line breaks, and HTML content are escaped correctly.

Sender fields

The API field is spelled CustomerSenderAddress. It is a sender address, not a reply-to address.

The configured mail service must permit the requested sender address. Setting this field does not grant permission to send from that address.

Embed the report

Email destination creation and full schedule definitions support:

• EmbedReport: whether to embed the report.
• EmbedFormat: IMAGE or HTML.

BodyFormat controls the message body. EmbedFormat controls the embedded report representation.

For a standard report attachment, use:

{
  "EmbedReport": false
}

Embedding affects how PBRS generates and includes the report. Do not assume enabling EmbedReport also retains the normal report attachment. Verify the resulting message with a controlled execution.

Configure a disk destination

Manage disk destinations through the source-specific schedule creation or update endpoint.

The following example is a destination object for inclusion in the schedule’s DiskDestinations array. It is not a complete schedule request.

{
  "DestinationName": "Sales export folder",
  "DestinationId": 0,
  "DestinationType": "Disk",
  "OutputFormat": "Acrobat Format (*.pdf)",
  "Enabled": true,
  "ParentId": 101,
  "OutputPath": "C:\\PBRSExports\\Sales"
}

Use DestinationId: 0 for a new destination. When retaining or updating an existing destination, provide its existing ID.

OutputPath refers to a path available to the machine executing the PBRS schedule, not the computer sending the API request.

Ensure that:

• The destination folder is accessible from the executing PBRS machine.
• The account used for report execution has permission to write to it.
• Any shared path is accessible from every machine that may execute the schedule.

JSON requires escaped backslashes in Windows paths.

Update destinations through the complete schedule

Use the endpoint for the schedule’s report source.

These endpoints update complete schedule definitions. They are not partial destination updates.

Preserve the complete destination collections

Include both EmailDestinations and DiskDestinations as complete, non-null arrays.

Keep the resulting destination configuration valid for the schedule.

Full update workflow

1. Retrieve the current schedule using the matching read endpoint.
2. Combine the retrieved values with your authoritative schedule configuration.
3. Preserve the schedule’s existing uniqueid.
4. Include the required recurrence configuration.
5. Include every email and disk destination you intend to retain.
6. Preserve the existing DestinationId for each retained destination.
7. Apply the intended output or destination changes.
8. Preserve unrelated schedule settings, including filters, parameters, bookmarks, rendering settings, and enabled state.
9. Submit the complete definition to the matching update endpoint.
10. Retrieve the schedule again and verify the result.

Full schedule updates return HTTP 200 with an empty response body. Do not attempt to parse that response as an updated schedule object.

See Create and Update Single Schedules for complete schedule request examples.

Verify the result

After changing a destination:

1. Retrieve the schedule again.
2. Confirm the destination IDs and enabled states.
3. Check recipients, subject, body format, output format, and disk paths.
4. Confirm that unrelated destinations remain present.
5. Run a controlled execution using an intended test recipient or output folder.
6. Monitor the execution and inspect the generated output.

Saving a destination does not execute the schedule or send a report. A successful configuration response confirms that the API accepted the change; verify delivery separately.

Troubleshooting