openemail.exports
Каждый метод этого пространства имён: его сигнатура, параметры, что он возвращает, и пример.
Методы
A zip of the whole workspace, as the Export page makes it: see what it would hold, start one, follow it while it is made and download it once it is ready.
exports.preview()
See what an export would hold
def preview( *, api_key: str | None = None, timeout: float | None = None,) -> ExportPreviewResourceReturns whether the workspace can be exported by the caller now, when the next export can start, the export still being made, if there is one, and how much an export would hold: conversations, attachments and their size, contacts, audiences, calendar events, templates, rules, labels, notes and addresses. When allowed is False, reason says why and counts is None.
Only the workspace owner, or a member whose role holds every permission, can export the workspace: an API key, or an access token connected with every address. A key or token limited to particular addresses or domains is 422 capability_unsupported, and an account the workspace cannot export for is 403 export_not_permitted.
Параметры
api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
OpenEmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Возвращает
ExportPreviewResource with allowed, reason, nextAvailableAt, activeExportId and counts.
Пример
from openemail import openemail preview = openemail.exports.preview() if preview['allowed'] and preview['nextAvailableAt'] is None: print('An export can start now:', preview['counts'])else: print('Not now:', preview['reason'], preview['nextAvailableAt'])Примечания
reasonisnot-permitted,mailbox-loginortwo-factor-required, andEXPORT_REFUSALSnames them.
Также доступно в
- API
GET /exports/preview- TypeScript
exports.preview()- Ruby
exports.preview- CLI
openemail exports preview
exports.list()
List the exports
def list( *, limit: int | None = None, offset: int | None = None, api_key: str | None = None, timeout: float | None = None,) -> ExportListResourceReturns the exports of the workspace, newest first, a page at a time, each with its status, its progress through the conversations and, once it is ready, its size, file name and when it is deleted. Pages are counted by position: raise offset= by limit= while hasMore is True.
Only the workspace owner, or a member whose role holds every permission, can export the workspace: an API key, or an access token connected with every address. A key or token limited to particular addresses or domains is 422 capability_unsupported, and an account the workspace cannot export for is 403 export_not_permitted.
Параметры
limitintExports per page, from 1 to 100. The server defaults to 25.
offsetintHow many exports to skip.
api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
OpenEmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Возвращает
ExportListResource, a dict with data, the exports on this page, total and hasMore.
Пример
from openemail import openemail page = openemail.exports.list(limit=10) ready = [export for export in page['data'] if export['status'] == 'ready'] print(f'{page["total"]} exports, {len(ready)} ready to download')Примечания
A workspace can be exported once a day, and each export is kept for a year, so the list stays short.
Также доступно в
- API
GET /exports- TypeScript
exports.list()- Ruby
exports.list- CLI
openemail exports list
exports.get()
Retrieve an export
def get( id: str, *, api_key: str | None = None, timeout: float | None = None,) -> ExportResourceReturns one export: its status, phase and progress while it is made, and once it is ready its size, file name and when it is deleted.
Only the workspace owner, or a member whose role holds every permission, can export the workspace: an API key, or an access token connected with every address. A key or token limited to particular addresses or domains is 422 capability_unsupported, and an account the workspace cannot export for is 403 export_not_permitted.
Параметры
idstrОбязательноThe export id from
startorlist.api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
OpenEmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Возвращает
ExportResource with id, status, phase, threadsDone, threadsTotal, sizeBytes, fileName, error, createdBy and its timestamps.
Пример
import time from openemail import openemail export = openemail.exports.get('exp_8c1e4a7f2b9d3e6a0c5f1b28') for _ in range(30): if export['status'] in ('ready', 'failed', 'expired'): break time.sleep(10) export = openemail.exports.get(export['id']) print(export['phase'], export['threadsDone'], 'of', export['threadsTotal']) print(export['status'], export['fileName'], export['sizeBytes'])Примечания
An unknown id is a 404, which raises
OpenEmailApiErrorwithis_not_foundset.
Также доступно в
- API
GET /exports/{id}- TypeScript
exports.get()- Ruby
exports.get- CLI
openemail exports get
exports.start()
Start an export
def start(*, api_key: str | None = None, timeout: float | None = None) -> ExportResourceStarts making a zip of the whole workspace, as Export now on the Export page does, and returns the export, queued. It is made in the background: poll get until status is ready, then download it. One export runs at a time, and a workspace can be exported once a day.
Only the workspace owner, or a member whose role holds every permission, can export the workspace: an API key, or an access token connected with every address. A key or token limited to particular addresses or domains is 422 capability_unsupported, and an account the workspace cannot export for is 403 export_not_permitted.
Параметры
api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
OpenEmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Возвращает
ExportResource for the new export.
Пример
from openemail import OpenEmailApiError, openemail try: export = openemail.exports.start()except OpenEmailApiError as error: if error.code in ('already_running', 'export_limit_reached'): print('No new export yet:', error.message) else: raiseelse: print(export['id'], export['status'])Примечания
With an OAuth access token it asks for a verification code: until the app has verified one, it is refused with 403
step_up_required, andis_step_up_requiredon the error says so. An API key is never asked.An export already being made is 409
already_running, and a workspace exported in the last day is 429export_limit_reached.The SDK does not retry it.
Также доступно в
- API
POST /exports- TypeScript
exports.start()- Ruby
exports.start- CLI
openemail exports start
exports.download()
Download an export
def download( id: str, *, api_key: str | None = None, timeout: float | None = None,) -> bytesReturns the zip of a ready export as bytes, the same file the Download action on the Export page saves.
Only the workspace owner, or a member whose role holds every permission, can export the workspace: an API key, or an access token connected with every address. A key or token limited to particular addresses or domains is 422 capability_unsupported, and an account the workspace cannot export for is 403 export_not_permitted.
Параметры
idstrОбязательноThe export id from
startorlist.api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
OpenEmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Возвращает
bytes holding the zip.
Пример
from pathlib import Path from openemail import openemail export = openemail.exports.get('exp_8c1e4a7f2b9d3e6a0c5f1b28')archive = openemail.exports.download(export['id'], timeout=600) target = Path(export['fileName'] or 'openemail-export.zip')target.write_bytes(archive) print(f'Saved {len(archive)} bytes to {target}')Примечания
With an OAuth access token it asks for a verification code: until the app has verified one, it is refused with 403
step_up_required, andis_step_up_requiredon the error says so. An API key is never asked.Before the export is
readythe call is 409export_not_ready, and an export older than a year is 409expired.The whole zip is held in memory, and a large workspace makes a large zip. Give the call a longer
timeout=for a large one, since the limit covers reading the whole file.