# Reports

## Create Saved Report

`print_mail.reports.create(ReportCreateParams**kwargs)  -> Report`

**post** `/print-mail/v1/reports`

Create a new saved report definition. Saved reports are SQL queries that can be executed later to generate
full exports or samples.

If you just want to do ad-hoc queries, you should use the `/reports/samples` endpoint.

### Parameters

- `sql_query: str`

  The SQL query defining the report.

- `description: Optional[str]`

  An optional user-friendly description for the report.

- `metadata: Optional[Dict[str, str]]`

  Optional key-value metadata associated with the report.

### Returns

- `class Report: …`

  Represents a saved Report definition.

  - `id: str`

    Unique identifier for the report.

  - `created_at: datetime`

    Timestamp when the report was created.

  - `live: bool`

    Indicates if the report is associated with the live or test environment.

  - `object: Literal["report"]`

    Always `report`.

    - `"report"`

  - `sql_query: str`

    The SQL query defining the report.

  - `updated_at: datetime`

    Timestamp when the report was last updated.

  - `description: Optional[str]`

    An optional user-friendly description for the report.

  - `metadata: Optional[Dict[str, str]]`

    Optional key-value metadata associated with the report.

### Example

```python
import os
from postgrid import PostGrid

client = PostGrid(
    print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"),  # This is the default and can be omitted
)
report = client.print_mail.reports.create(
    sql_query="SELECT id, status FROM orders WHERE created_at > ?",
    description="Recent Orders",
    metadata={
        "team": "Sales"
    },
)
print(report.id)
```

#### Response

```json
{
  "id": "report_123",
  "object": "report",
  "live": false,
  "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?",
  "description": "Recent Orders",
  "metadata": {
    "team": "Sales"
  },
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:00:00Z"
}
```

## Run Ad-hoc Query

`print_mail.reports.sample(ReportSampleParams**kwargs)  -> ReportSample`

**post** `/print-mail/v1/reports/samples`

Run an ad-hoc SQL query against your data lake and get a sample of the results.
This is useful for quickly testing queries without saving them as a report.
The query execution time and result size are limited.

### Parameters

- `sql_query: str`

  The SQL query to execute for the sample.

- `limit: Optional[int]`

  Maximum number of rows to return in the sample.

- `params: Optional[SequenceNotStr[str]]`

  Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1).

### Returns

- `class ReportSample: …`

  Represents the result of a report sample query.

  - `id: str`

    Unique identifier for the sample query result.

  - `records: List[Dict[str, object]]`

    The actual data records returned by the sample query.

  - `report: Optional[str]`

    The ID of the report this sample was generated from, or null for ad-hoc samples.

### Example

```python
import os
from postgrid import PostGrid

client = PostGrid(
    print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"),  # This is the default and can be omitted
)
report_sample = client.print_mail.reports.sample(
    sql_query="SELECT id FROM contacts LIMIT 5",
    limit=5,
    params=[],
)
print(report_sample.id)
```

#### Response

```json
{
  "id": "sample_abc",
  "report": "report_123",
  "records": [
    {
      "id": "order_1"
    },
    {
      "id": "order_2"
    }
  ]
}
```

## Update Report

`print_mail.reports.update(strid, ReportUpdateParams**kwargs)  -> Report`

**post** `/print-mail/v1/reports/{id}`

Update an existing saved report definition. You can change the query, description, or metadata.

### Parameters

- `id: str`

- `description: Optional[str]`

  An optional user-friendly description for the report. Set to null to remove.

- `metadata: Optional[Dict[str, str]]`

  Optional key-value metadata associated with the report. Set to null to remove.

- `sql_query: Optional[str]`

  The SQL query defining the report.

### Returns

- `class Report: …`

  Represents a saved Report definition.

  - `id: str`

    Unique identifier for the report.

  - `created_at: datetime`

    Timestamp when the report was created.

  - `live: bool`

    Indicates if the report is associated with the live or test environment.

  - `object: Literal["report"]`

    Always `report`.

    - `"report"`

  - `sql_query: str`

    The SQL query defining the report.

  - `updated_at: datetime`

    Timestamp when the report was last updated.

  - `description: Optional[str]`

    An optional user-friendly description for the report.

  - `metadata: Optional[Dict[str, str]]`

    Optional key-value metadata associated with the report.

### Example

```python
import os
from postgrid import PostGrid

client = PostGrid(
    print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"),  # This is the default and can be omitted
)
report = client.print_mail.reports.update(
    id="id",
    description="Recent Orders (Updated)",
)
print(report.id)
```

#### Response

```json
{
  "id": "report_123",
  "object": "report",
  "live": false,
  "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?",
  "description": "Recent Orders",
  "metadata": {
    "team": "Sales"
  },
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:00:00Z"
}
```

## List Saved Reports

`print_mail.reports.list(ReportListParams**kwargs)  -> SyncSkipLimit[Report]`

**get** `/print-mail/v1/reports`

Retrieve a list of saved reports for your organization.

### Parameters

- `limit: Optional[int]`

- `search: Optional[str]`

  You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details.

- `skip: Optional[int]`

### Returns

- `class Report: …`

  Represents a saved Report definition.

  - `id: str`

    Unique identifier for the report.

  - `created_at: datetime`

    Timestamp when the report was created.

  - `live: bool`

    Indicates if the report is associated with the live or test environment.

  - `object: Literal["report"]`

    Always `report`.

    - `"report"`

  - `sql_query: str`

    The SQL query defining the report.

  - `updated_at: datetime`

    Timestamp when the report was last updated.

  - `description: Optional[str]`

    An optional user-friendly description for the report.

  - `metadata: Optional[Dict[str, str]]`

    Optional key-value metadata associated with the report.

### Example

```python
import os
from postgrid import PostGrid

client = PostGrid(
    print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"),  # This is the default and can be omitted
)
page = client.print_mail.reports.list()
page = page.data[0]
print(page.id)
```

#### Response

```json
{
  "object": "list",
  "limit": 10,
  "skip": 0,
  "totalCount": 1,
  "data": [
    {
      "id": "report_123",
      "object": "report",
      "live": false,
      "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?",
      "description": "Recent Orders",
      "metadata": {
        "team": "Sales"
      },
      "createdAt": "2023-10-27T10:00:00Z",
      "updatedAt": "2023-10-27T10:00:00Z"
    }
  ]
}
```

## Retrieve Saved Report

`print_mail.reports.retrieve(strid)  -> Report`

**get** `/print-mail/v1/reports/{id}`

Retrieve the details of a specific saved report by its ID.

### Parameters

- `id: str`

### Returns

- `class Report: …`

  Represents a saved Report definition.

  - `id: str`

    Unique identifier for the report.

  - `created_at: datetime`

    Timestamp when the report was created.

  - `live: bool`

    Indicates if the report is associated with the live or test environment.

  - `object: Literal["report"]`

    Always `report`.

    - `"report"`

  - `sql_query: str`

    The SQL query defining the report.

  - `updated_at: datetime`

    Timestamp when the report was last updated.

  - `description: Optional[str]`

    An optional user-friendly description for the report.

  - `metadata: Optional[Dict[str, str]]`

    Optional key-value metadata associated with the report.

### Example

```python
import os
from postgrid import PostGrid

client = PostGrid(
    print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"),  # This is the default and can be omitted
)
report = client.print_mail.reports.retrieve(
    "id",
)
print(report.id)
```

#### Response

```json
{
  "id": "report_123",
  "object": "report",
  "live": false,
  "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?",
  "description": "Recent Orders",
  "metadata": {
    "team": "Sales"
  },
  "createdAt": "2023-10-27T10:00:00Z",
  "updatedAt": "2023-10-27T10:00:00Z"
}
```

## Delete Saved Report

`print_mail.reports.delete(strid)  -> DeletedResponse`

**delete** `/print-mail/v1/reports/{id}`

Delete a saved report definition. This action cannot be undone.
Associated exports are not automatically deleted.

### Parameters

- `id: str`

### Returns

- `class DeletedResponse: …`

  Generic response for delete operations.

  - `id: str`

    The ID of the deleted resource.

  - `deleted: Literal[true]`

    Indicates the resource was successfully deleted.

    - `true`

### Example

```python
import os
from postgrid import PostGrid

client = PostGrid(
    print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"),  # This is the default and can be omitted
)
deleted_response = client.print_mail.reports.delete(
    "id",
)
print(deleted_response.id)
```

#### Response

```json
{
  "id": "report_123",
  "deleted": true
}
```

## Domain Types

### Deleted Response

- `class DeletedResponse: …`

  Generic response for delete operations.

  - `id: str`

    The ID of the deleted resource.

  - `deleted: Literal[true]`

    Indicates the resource was successfully deleted.

    - `true`

### Report

- `class Report: …`

  Represents a saved Report definition.

  - `id: str`

    Unique identifier for the report.

  - `created_at: datetime`

    Timestamp when the report was created.

  - `live: bool`

    Indicates if the report is associated with the live or test environment.

  - `object: Literal["report"]`

    Always `report`.

    - `"report"`

  - `sql_query: str`

    The SQL query defining the report.

  - `updated_at: datetime`

    Timestamp when the report was last updated.

  - `description: Optional[str]`

    An optional user-friendly description for the report.

  - `metadata: Optional[Dict[str, str]]`

    Optional key-value metadata associated with the report.

# Samples

## Sample a Saved Report

`print_mail.reports.samples.create(strid, SampleCreateParams**kwargs)  -> ReportSample`

**post** `/print-mail/v1/reports/{id}/samples`

Run the query associated with a saved report and get a sample of the results.
This allows getting up to 1000 rows of resutls but the runtime of the query is limited to 30 seconds.
If you need more rows or longer runtime, you should create an export from this report.

### Parameters

- `id: str`

- `limit: Optional[int]`

  Maximum number of rows to return in the sample.

- `params: Optional[SequenceNotStr[str]]`

  Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1).

### Returns

- `class ReportSample: …`

  Represents the result of a report sample query.

  - `id: str`

    Unique identifier for the sample query result.

  - `records: List[Dict[str, object]]`

    The actual data records returned by the sample query.

  - `report: Optional[str]`

    The ID of the report this sample was generated from, or null for ad-hoc samples.

### Example

```python
import os
from postgrid import PostGrid

client = PostGrid(
    print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"),  # This is the default and can be omitted
)
report_sample = client.print_mail.reports.samples.create(
    id="id",
    limit=10,
    params=["2023-10-01T00:00:00Z"],
)
print(report_sample.id)
```

#### Response

```json
{
  "id": "sample_abc",
  "report": "report_123",
  "records": [
    {
      "id": "order_1"
    },
    {
      "id": "order_2"
    }
  ]
}
```

## Domain Types

### Report Sample

- `class ReportSample: …`

  Represents the result of a report sample query.

  - `id: str`

    Unique identifier for the sample query result.

  - `records: List[Dict[str, object]]`

    The actual data records returned by the sample query.

  - `report: Optional[str]`

    The ID of the report this sample was generated from, or null for ad-hoc samples.

### Report Sample Create Base

- `class ReportSampleCreateBase: …`

  Base properties for creating a report sample.

  - `limit: Optional[int]`

    Maximum number of rows to return in the sample.

  - `params: Optional[List[str]]`

    Optional parameters to bind to the SQL query (e.g., for placeholders like ? or $1).

# Exports

## Create a Report Export

`print_mail.reports.exports.create(strreport_id, ExportCreateParams**kwargs)  -> ReportExport`

**post** `/print-mail/v1/reports/{reportID}/exports`

Create a new export job for a saved report. This runs the report's query
asynchronously and generates a downloadable CSV file with the full results.
Your queries can run for up to 13 minutes the resulting file can be up to 100mb large.

### Parameters

- `report_id: str`

- `description: Optional[str]`

  An optional user-friendly description for the export.

- `metadata: Optional[Dict[str, str]]`

  Optional key-value metadata associated with the export.

- `params: Optional[SequenceNotStr[str]]`

  Optional parameters to bind to the SQL query of the associated report.

### Returns

- `class ReportExport: …`

  Represents a report export job and its results.

  - `id: str`

    Unique identifier for the report export.

  - `created_at: datetime`

    Timestamp when the export was created.

  - `live: bool`

    Indicates if the export is associated with the live or test environment.

  - `object: Literal["report_export"]`

    Always `report_export`.

    - `"report_export"`

  - `report: Report`

    Details of the report this export was generated from.

    - `id: str`

      The ID of the report.

    - `sql_query: str`

      The SQL query used for this export (snapshotted at creation time).

  - `updated_at: datetime`

    Timestamp when the export was last updated (e.g., finished generation).

  - `description: Optional[str]`

    An optional user-friendly description for the export.

  - `failure_message: Optional[str]`

    If export generation failed, this contains the error message.

  - `metadata: Optional[Dict[str, str]]`

    Optional key-value metadata associated with the export.

  - `output_url: Optional[str]`

    A signed URL to download the exported data (CSV format). Available when generation is complete and successful.

  - `params: Optional[List[str]]`

    Optional parameters to bind to the SQL query of the associated report.

  - `row_count: Optional[int]`

    The number of rows in the exported data.

  - `size_in_bytes: Optional[int]`

    The size of the generated export file in bytes.

  - `truncated_to_bytes: Optional[int]`

    If the output was truncated, indicates the byte limit reached.

### Example

```python
import os
from postgrid import PostGrid

client = PostGrid(
    print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"),  # This is the default and can be omitted
)
report_export = client.print_mail.reports.exports.create(
    report_id="reportID",
    description="October Orders Export",
    params=["2023-10-01T00:00:00Z"],
)
print(report_export.id)
```

#### Response

```json
{
  "id": "report_export_123",
  "object": "report_export",
  "live": false,
  "report": {
    "id": "report_123",
    "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?"
  },
  "params": [
    "2023-10-01T00:00:00Z"
  ],
  "description": "October Orders Export",
  "outputURL": "https://s3.amazonaws.com/...",
  "sizeInBytes": 1024,
  "rowCount": 50,
  "createdAt": "2023-10-27T11:00:00Z",
  "updatedAt": "2023-10-27T11:05:00Z"
}
```

## Get Report Export

`print_mail.reports.exports.retrieve(strexport_id, ExportRetrieveParams**kwargs)  -> ReportExport`

**get** `/print-mail/v1/reports/{reportID}/exports/{exportID}`

Retrieve the status and details of a specific report export job.
Check the `outputURL` property for the download link once generation is complete.

### Parameters

- `report_id: str`

- `export_id: str`

### Returns

- `class ReportExport: …`

  Represents a report export job and its results.

  - `id: str`

    Unique identifier for the report export.

  - `created_at: datetime`

    Timestamp when the export was created.

  - `live: bool`

    Indicates if the export is associated with the live or test environment.

  - `object: Literal["report_export"]`

    Always `report_export`.

    - `"report_export"`

  - `report: Report`

    Details of the report this export was generated from.

    - `id: str`

      The ID of the report.

    - `sql_query: str`

      The SQL query used for this export (snapshotted at creation time).

  - `updated_at: datetime`

    Timestamp when the export was last updated (e.g., finished generation).

  - `description: Optional[str]`

    An optional user-friendly description for the export.

  - `failure_message: Optional[str]`

    If export generation failed, this contains the error message.

  - `metadata: Optional[Dict[str, str]]`

    Optional key-value metadata associated with the export.

  - `output_url: Optional[str]`

    A signed URL to download the exported data (CSV format). Available when generation is complete and successful.

  - `params: Optional[List[str]]`

    Optional parameters to bind to the SQL query of the associated report.

  - `row_count: Optional[int]`

    The number of rows in the exported data.

  - `size_in_bytes: Optional[int]`

    The size of the generated export file in bytes.

  - `truncated_to_bytes: Optional[int]`

    If the output was truncated, indicates the byte limit reached.

### Example

```python
import os
from postgrid import PostGrid

client = PostGrid(
    print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"),  # This is the default and can be omitted
)
report_export = client.print_mail.reports.exports.retrieve(
    export_id="exportID",
    report_id="reportID",
)
print(report_export.id)
```

#### Response

```json
{
  "id": "report_export_123",
  "object": "report_export",
  "live": false,
  "report": {
    "id": "report_123",
    "sqlQuery": "SELECT id, status FROM orders WHERE created_at > ?"
  },
  "params": [
    "2023-10-01T00:00:00Z"
  ],
  "description": "October Orders Export",
  "outputURL": "https://s3.amazonaws.com/...",
  "sizeInBytes": 1024,
  "rowCount": 50,
  "createdAt": "2023-10-27T11:00:00Z",
  "updatedAt": "2023-10-27T11:05:00Z"
}
```

## Delete Report Export

`print_mail.reports.exports.delete(strexport_id, ExportDeleteParams**kwargs)  -> DeletedResponse`

**delete** `/print-mail/v1/reports/{reportID}/exports/{exportID}`

Delete a completed or failed report export job and its associated output file (if any).
This action cannot be undone. You cannot delete an export that is still generating.

### Parameters

- `report_id: str`

- `export_id: str`

### Returns

- `class DeletedResponse: …`

  Generic response for delete operations.

  - `id: str`

    The ID of the deleted resource.

  - `deleted: Literal[true]`

    Indicates the resource was successfully deleted.

    - `true`

### Example

```python
import os
from postgrid import PostGrid

client = PostGrid(
    print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"),  # This is the default and can be omitted
)
deleted_response = client.print_mail.reports.exports.delete(
    export_id="exportID",
    report_id="reportID",
)
print(deleted_response.id)
```

#### Response

```json
{
  "id": "report_export_123",
  "deleted": true
}
```

## Domain Types

### Report Export

- `class ReportExport: …`

  Represents a report export job and its results.

  - `id: str`

    Unique identifier for the report export.

  - `created_at: datetime`

    Timestamp when the export was created.

  - `live: bool`

    Indicates if the export is associated with the live or test environment.

  - `object: Literal["report_export"]`

    Always `report_export`.

    - `"report_export"`

  - `report: Report`

    Details of the report this export was generated from.

    - `id: str`

      The ID of the report.

    - `sql_query: str`

      The SQL query used for this export (snapshotted at creation time).

  - `updated_at: datetime`

    Timestamp when the export was last updated (e.g., finished generation).

  - `description: Optional[str]`

    An optional user-friendly description for the export.

  - `failure_message: Optional[str]`

    If export generation failed, this contains the error message.

  - `metadata: Optional[Dict[str, str]]`

    Optional key-value metadata associated with the export.

  - `output_url: Optional[str]`

    A signed URL to download the exported data (CSV format). Available when generation is complete and successful.

  - `params: Optional[List[str]]`

    Optional parameters to bind to the SQL query of the associated report.

  - `row_count: Optional[int]`

    The number of rows in the exported data.

  - `size_in_bytes: Optional[int]`

    The size of the generated export file in bytes.

  - `truncated_to_bytes: Optional[int]`

    If the output was truncated, indicates the byte limit reached.