synology_apm.sdk.collections.m365_mail_export module

M365 mail export — Exchange mailbox and Group mailbox PST export operations.

class synology_apm.sdk.collections.m365_mail_export.M365ExportStartResult(execution_id, ready_to_download, export_name, location, workload, version)

Bases: object

Return value of ExchangeExportCollection.start() and GroupExportCollection.start().

Variables:
execution_id: str
ready_to_download: bool
export_name: str
location: VersionLocation
workload: M365Workload
version: WorkloadVersion
class synology_apm.sdk.collections.m365_mail_export.ExchangeExportCollection(session)

Bases: _BaseM365ExportCollection

Collection interface for Exchange mailbox PST export operations.

Accessed via APMClient.m365.exchange_export; should not be instantiated directly.

All methods operate on Exchange workloads only. The workload must be obtained via APMClient.m365.workloads.get() before calling methods on this collection.

async start(workload, version, *, archive_mailbox=False, export_name=None, location_id=None)

Start an Exchange mailbox PST export.

Parameters:

  • workload (M365Workload) – Exchange M365Workload (from apm.m365.workloads.get() or get_by_name()).

  • version (WorkloadVersion) – Backup version to export (from list_versions / get_latest_version).

  • archive_mailbox (bool) – If True, export the archive mailbox instead of the primary mailbox.

  • export_name (str | None) – Filename shown in the browser download dialog (e.g. “alice_20260514.pst”). Auto-generated from the workload UPN and today’s date if omitted.

  • location_id (str | None) – VersionLocation.location_id of the specific copy to export from; defaults to the first available location. The selected location is embedded in the returned M365ExportStartResult.

Returns:

M365ExportStartResult with execution_id, ready_to_download, and export_name. If ready_to_download is True, call get_download_url_by_ready_result() immediately. If False, poll get_activity_by_result() until status is READY_TO_DOWNLOAD, then call get_download_url_by_activity().

Raises:

  • ResourceNotFoundError – No mailbox folders found for this version, or location_id not found.

  • APIError – Version has no location data, or APM rejected the export request.

Return type:

M365ExportStartResult

async cancel(activity)

Cancel an in-progress export task.

Parameters:

activity (M365ExportActivity) – M365ExportActivity obtained from list().

Raises:

APIError – APM rejected the cancel request.

async get_activity_by_result(result)

Find the M365ExportActivity corresponding to a started export.

Searches the activity list by matching both the backup server namespace and the internal execution ID. Returns None when the activity is not yet visible in the list (may occur immediately after start()).

Parameters:

result (M365ExportStartResult) – M365ExportStartResult returned by start().

Returns:

The matching M365ExportActivity, or None if not yet available.

Return type:

M365ExportActivity | None

async get_download_url_by_activity(activity)

Retrieve the time-limited download URL for a completed export.

Use this when downloading a previously completed export (status READY_TO_DOWNLOAD). For exports started in the current session, prefer get_download_url_by_ready_result().

Parameters:

activity (M365ExportActivity) – M365ExportActivity obtained from list() with status READY_TO_DOWNLOAD.

Returns:

Full HTTPS download URL for the PST file.

Raises:
Return type:

str

async get_download_url_by_ready_result(result)

Retrieve the time-limited download URL for an immediately ready export.

Use this immediately after start() when M365ExportStartResult.ready_to_download is True. If ready_to_download is False, poll get_activity_by_result() until status is READY_TO_DOWNLOAD, then call get_download_url_by_activity() instead.

Parameters:

result (M365ExportStartResult) – M365ExportStartResult from start() with ready_to_download=True.

Returns:

Full HTTPS download URL for the PST file.

Raises:
Return type:

str

async list(workload, limit=500, offset=0)

List export tasks for a workload.

Parameters:

  • workload (M365Workload) – M365Workload (Exchange or Group, from apm.m365.workloads.get() or get_by_name()).

  • limit (int) – Maximum records to return (default 500).

  • offset (int) – Pagination start offset (default 0).

Returns:

(list of M365ExportActivity, total count)

Return type:

tuple[list[M365ExportActivity], int]

class synology_apm.sdk.collections.m365_mail_export.GroupExportCollection(session)

Bases: _BaseM365ExportCollection

Collection interface for Group mailbox PST export operations.

Accessed via APMClient.m365.group_export; should not be instantiated directly.

All methods operate on Group workloads only. The workload must be obtained via APMClient.m365.workloads.get() before calling methods on this collection. Group mailboxes do not have an archive mailbox.

async start(workload, version, *, export_name=None, location_id=None)

Start a Group mailbox PST export.

Parameters:

  • workload (M365Workload) – Group M365Workload (from apm.m365.workloads.get() or get_by_name()).

  • version (WorkloadVersion) – Backup version to export (from list_versions / get_latest_version).

  • export_name (str | None) – Filename shown in the browser download dialog (e.g. “group_20260514.pst”). Auto-generated from the workload name and today’s date if omitted.

  • location_id (str | None) – VersionLocation.location_id of the specific copy to export from; defaults to the first available location. The selected location is embedded in the returned M365ExportStartResult.

Returns:

M365ExportStartResult with execution_id, ready_to_download, and export_name. If ready_to_download is True, call get_download_url_by_ready_result() immediately. If False, poll get_activity_by_result() until status is READY_TO_DOWNLOAD, then call get_download_url_by_activity().

Raises:

  • ResourceNotFoundError – No mailbox folders found for this version, or location_id not found.

  • APIError – Version has no location data, or APM rejected the export request.

Return type:

M365ExportStartResult

async cancel(activity)

Cancel an in-progress export task.

Parameters:

activity (M365ExportActivity) – M365ExportActivity obtained from list().

Raises:

APIError – APM rejected the cancel request.

async get_activity_by_result(result)

Find the M365ExportActivity corresponding to a started export.

Searches the activity list by matching both the backup server namespace and the internal execution ID. Returns None when the activity is not yet visible in the list (may occur immediately after start()).

Parameters:

result (M365ExportStartResult) – M365ExportStartResult returned by start().

Returns:

The matching M365ExportActivity, or None if not yet available.

Return type:

M365ExportActivity | None

async get_download_url_by_activity(activity)

Retrieve the time-limited download URL for a completed export.

Use this when downloading a previously completed export (status READY_TO_DOWNLOAD). For exports started in the current session, prefer get_download_url_by_ready_result().

Parameters:

activity (M365ExportActivity) – M365ExportActivity obtained from list() with status READY_TO_DOWNLOAD.

Returns:

Full HTTPS download URL for the PST file.

Raises:
Return type:

str

async get_download_url_by_ready_result(result)

Retrieve the time-limited download URL for an immediately ready export.

Use this immediately after start() when M365ExportStartResult.ready_to_download is True. If ready_to_download is False, poll get_activity_by_result() until status is READY_TO_DOWNLOAD, then call get_download_url_by_activity() instead.

Parameters:

result (M365ExportStartResult) – M365ExportStartResult from start() with ready_to_download=True.

Returns:

Full HTTPS download URL for the PST file.

Raises:
Return type:

str

async list(workload, limit=500, offset=0)

List export tasks for a workload.

Parameters:

  • workload (M365Workload) – M365Workload (Exchange or Group, from apm.m365.workloads.get() or get_by_name()).

  • limit (int) – Maximum records to return (default 500).

  • offset (int) – Pagination start offset (default 0).

Returns:

(list of M365ExportActivity, total count)

Return type:

tuple[list[M365ExportActivity], int]