Retrieve a list of sent campaigns (calendar)

The calendar Ortto endpoint of the campaign entity is used to retrieve a list of sent email, sms and push notification campaigns for a specified period of time.

This page provides descriptions of this endpoint’s:

request resource and method,
valid parameters, headers, and request body values, as well as
the response payload.

HTTP method and request resources


 POST https://api.ap3api.com/v1/campaign/calendar

NOTE: Ortto customers who have their instance region set to Australia or Europe will need to use specific service endpoints relative to the region:

Australia: https://api.au.ap3api.com/
Europe: https://api.eu.ap3api.com/

For example: https://api.eu.ap3api.com/v1/<entity/endpoint>

All other Ortto users will use the default service endpoint (https://api.ap3api.com/).

Path and query parameters

This endpoint takes no additional path and/or query parameters.

Headers

This endpoint requires a custom API key and content type (application/json for the request body) in the header of the request:

X-Api-Key: CUSTOM-PRIVATE-API-KEY
Content-Type: application/json

Request body

The request body consists of a JSON object whose valid elements are listed in the table below.

The following JSON objects are examples of field and object data that Ortto can recognize to get campaign data from your Ortto account’s CDP.

json
 {
  "start":{
        "year": 2024,
        "month":3
    },
  "end":{
        "year": 2024,
        "month": 4
    },
    "timezone": "Australia/Sydney"
}

Valid request body elements

The following table lists all valid request body elements (arrays, objects, or fields), which are available to this endpoint.

Element	Type	Requirement	Description
`start`	`object`	Required	Specify the timeframe for which you want a list of sent campaigns using the start and end objects. These objects require values for: `year`: formatted as `YYYY` `month`: as an integer `1`–`12`
`end`	`object`	Required
`timezone`	`string`	Required	Specify the timezone for which you want the list of sent campaigns. See the List of timezones for valid timezone values.

Element

Type

Requirement

Description

start

object

Required

Specify the timeframe for which you want a list of sent campaigns using the start and end objects.

These objects require values for:

year: formatted as YYYY
month: as an integer 1–12

end

object

Required

timezone

string

Required

Specify the timezone for which you want the list of sent campaigns. See the List of timezones for valid timezone values.

Response payload

The response payload consists of a JSON object with the elements listed in the table below.

The following JSON object is an example of the custom field data that Ortto retrieves from your Ortto account’s CDP after a request to this endpoint.

Example get sent campaigns response payload from Ortto’s CDP

json
 {
    "campaigns": [
        {
            "id": "660103687595166e512b62dd",
            "name": "Booked car hire raw value",
            "type": "email",
            "state": "sent",
            "asset_id": "6704bf40f66879edb43926e7",
            "audience": {
                "id": "000000000000000000000000",
                "type": "filter",
                "filter": {
                    "$and": [
                        {
                            "$and": [
                                {
                                    "$act::has_occurred": {
                                        "formData": {
                                            "mode": "hasOccurred",
                                            "label": "Booked car hire has occurred in the last 15 days  ",
                                            "hasOccurred": {
                                                "op": "$act::has_occurred",
                                                "label": "has occurred"
                                            },
                                            "when": {
                                                "op": "$when::in_the_last",
                                                "value": 15,
                                                "label": "in the last 15 days"
                                            }
                                        },
                                        "label": "Booked car hire has occurred in the last 15 days  ",
                                        "field_id": "act:cm:booked-car-hire",
                                        "timezone": "Australia/Adelaide",
                                        "when_type": "in_the_last",
                                        "when_days": 15,
                                        "name": "Booked car hire",
                                        "icon": "delivery-icon"
                                    }
                                }
                            ]
                        }
                    ]
                },
                "contacts_count": 4,
                "all_subscribers": false
            },
            "enable_schedule": null,
            "sending_at": "Tue 26 Mar 2024 4:23 PM",
            "published_at": "Tue 26 Mar 2024 4:23 PM",
            "sent_at": "Tue 26 Mar 2024 4:33 PM",
            "scheduled_location": "",
            "scheduled_use_local_time": false,
            "scheduled_local_time": "",
            "screenshot_url": "<value>"
        },
       {
            "id": "62e20f4f7365f0edc7e892d4",
            "name": "Sender ID",
            "type": "SMS",
            "state": "sent",
            "asset_id": "5804bf40f66879edb43924c9",
            "audience": {
                "id": "000000000000000000000000",
                "type": "filter",
                "filter": {
                    "$and": [
                        {
                            "$and": [
                                {
                                    "$phn::is": {
                                        "value": {
                                            "c": "61",
                                            "n": "411222333"
                                        },
                                        "label": "Phone number is +61 411 222 333",
                                        "field_id": "phn::phone",
                                        "timezone": "Australia/Adelaide",
                                        "name": "Phone number",
                                        "icon": "contact-icon"
                                    }
                                }
                            ]
                        }
                    ]
                },
                "contacts_count": 1,
                "all_subscribers": false
            },
            "enable_schedule": null,
            "sending_at": "Thu 28 Jul 2022 2:47 PM",
            "published_at": "Thu 28 Jul 2022 2:47 PM",
            "sent_at": "Thu 28 Jul 2022 2:47 PM",
            "scheduled_location": "",
            "scheduled_use_local_time": false,
            "scheduled_local_time": "",
            "screenshot_url": "<value>",
            "dark_mode_screenshot_url": "<value>"
        },
        {
            "id": "250103687595166e512b68d9",
            "name": "Spring sale",
            "type": "email",
            "state": "sent",
            "asset_id": "6804bf40f66879edb4392a12",
            "a_b_testing": {
                "winner": "a",
                "variant_a_asset_id": "670486834443e9e1f4c585c2",
                "variant_a_contacts_count": 2000,
                "variant_b_asset_id": "670486834443e9e1f4c585c3",
                "variant_b_contacts_count": 1989,
                "target": "subject",
                "decider": "open-rate",
                "test_duration_hours": 4,
                "test_percentage": 49,
                "test_size": 0,
                "delivery_option": "",
                "schedule_a": {
                    "local_time": "2024/04/18 12:09 PM",
                    "location": ""
                },
                "schedule_b": {
                    "local_time": "2024/04/18 12:09 PM",
                    "location": ""
                },
                "use_local_time": false,
                "variant_a_screenshot_url": "<value>",
                "variant_b_screenshot_url": "<value>"
            },
        }
    ],
    "meta": {
        "total_campaigns": 33,
        "total_active_campaigns": 0
    },
    "today": "Fri 26 Apr 2024 9:48 AM"
}

Response payload elements

The following table lists all elements (arrays, objects, or fields) in the response from a request to this endpoint.

Element		Type	Description
`campaigns`		`array` of campaign `objects`	An array of campaign objects with an the campaign name, number of subscribers, whether the campaign was A/B tested, the send date, and the campaign type
	`id`	`string`	The campaign’s unique identifier
	`name`	`string`	The internal name given to the campaign
	`type`	`string`	The type of campaign, e.g. `email`, `sms`
	`state`	`string`	The state of the campaign, e.g. `sent` for a single-send email campaign
	`asset_id`	`string`	The ID of the asset used in this campaign. Can be used to look up the report stats on the GET Report endpoint
	`resend`	`string`	If this campaign was resent to contacts who didn't open the first email, this is the `asset_id` of the resent email. (Note, reporting is separate for each asset)
	`a_b_testing`	`object`	For an A/B tested campaign, this object will identify the winning variant (A or B) and key details
	`audience`	`object`	The conditions used to create the campaign audience, e.g. the `filter` conditions, or `tag` name
	`sending_at`	`string`	The time/date the campaign started sending
	`published_at`	`string`	The time/date the campaign was last published
	`sent_at`	`string`	The time/date the campaign finished sending
	`resent_at`	`string`	The time/date the campaign was resent to those who didn't open the original send.
	`enable_schedule_at` / `scheduled_at`	`string`	The time/date the campaign was scheduled to send at
	`scheduled_location`	`string`	The timezone in which the send was scheduled
	`scheduled_use_local_time`	`boolean`	If `true`, the campaign was scheduled to deliver in a contact’s local timezone (if known)
	`schedule_local_time`	`string`	The local time/date the campaign was scheduled for
`meta`		`object`	Stats about all account campaigns, not just those returned for the provided date range
	`total_campaigns`	`integer`	The total number of email, SMS and push notification campaigns which are not draft, canceled, or deleted. The total is for all time.
	`total_active_campaigns`	`integer`	The count of all campaigns in your Ortto account
`today`		`string`	The time and date the response was sent