QUERY v2/EviMail/Batches

HTTP Method: QUERY

Description:

This endpoint retrieves a list of all bulk email batches available for a specific SiteId. It supports filtering by state, limiting the number of results, and pagination via a cursor.

Input Parameters

• OwnerSiteId (Guid)

  • Unique identifier of the site for which the data is being retrieved.

• OwnerEmail (string, optional)

  • Email of the owner of the batches to filter the results.

• State (string, optional)

  • Filters results by the state of the batches (e.g., Draft, Scheduled, Completed).

• Cursor (string, optional)

  • Token representing the state of a previous query. It enables the continuation of result retrieval from where the last query ended.

• Limit (int)

  • Specifies the maximum number of results to return. Must be between 1 and 100.

• Order (int, optional)

  • Determines the sorting order of the results:

    • 0 for ascending order.

    • 1 for descending order.

Output Parameters

• Cursor (string)

  • The cursor token for this query, which can be used in subsequent requests to continue retrieving results.

• Results (IEnumerable<Batch>)

  • A collection of batch records matching the query parameters. Each batch has the following properties:

    • Status (string): The current state of the batch (e.g., Draft, Scheduled).

    • Description (string): A descriptive text identifying the batch.

    • TotalCount (int): Total number of recipients in the batch.

    • ScheduledFor (datetime): The date and time the batch is scheduled for processing.

    • StartedOn (datetime): The date and time the batch started processing.

    • OwnerEmail (string): Email of the batch's owner.

    • BatchId (Guid): Unique identifier of the batch.

Request Example

Basic Query:

GET /v2/EviMail/Batches?OwnerSiteId=6fda9a24-03c9-4b5b-8721-645cfdc9f4d8&Limit=50
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

Query with Filters:

GET /v2/EviMail/Batches?OwnerSiteId=6fda9a24-03c9-4b5b-8721-645cfdc9f4d8&State=Scheduled&Limit=20&Order=1&OwnerEmail=owner@example.com
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

Query with Cursor:

GET /v2/EviMail/Batches?OwnerSiteId=6fda9a24-03c9-4b5b-8721-645cfdc9f4d8&Cursor=eyJwb3NpdGlvbiI6NTA=&Limit=20
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

Response Example

{
    "Cursor": "eyJwb3NpdGlvbiI6NzA=",
    "Results": [
        {
            "Status": "Scheduled",
            "Description": "Monthly newsletter batch",
            "TotalCount": 1500,
            "ScheduledFor": "2024-11-20T09:00:00Z",
            "StartedOn": "2024-11-19T08:00:00Z",
            "OwnerEmail": "owner@example.com",
            "BatchId": "a5b1f3f2-5c73-4b6d-88b9-73d81a9c5f8e"
        },
        {
            "Status": "Completed",
            "Description": "Welcome emails batch",
            "TotalCount": 500,
            "ScheduledFor": "2024-11-15T10:00:00Z",
            "StartedOn": "2024-11-15T10:00:00Z",
            "OwnerEmail": "owner@example.com",
            "BatchId": "b8f3c2e1-7d2b-4a6c-bd85-d9c5e9f9c7f2"
        }
    ]
}

Notes

• Cursor for Pagination:

  • The Cursor token returned in the response must be used in subsequent queries to fetch the next set of results.

  • Example: If the first query returns 50 results and a cursor, use the cursor in the next query to fetch the following 50 results.

• Limit Validation:

  • Ensure the Limit parameter is between 1 and 100. Requests exceeding this range will return an error.

• Sorting Order:

  • Use the Order parameter to control sorting:

    • 0 for ascending (e.g., oldest to newest).

    • 1 for descending (e.g., newest to oldest).

• Filtering Flexibility:

  • Use OwnerEmail and State for granular filtering to retrieve specific records efficiently.