One-time sending in future

# PushExpress -- one-time sending in future API reference

Version date: 20 December 2024

---

To authorize, you need to add the header "Authorization: Bearer ..." (get your API KEY in your personal account on "Personal" tab).

Endpoints

• Create a OneSend Scheduler

• Get a OneSend Scheduler

---

Create a OneSend Scheduler

POST https://core.push.express/api/b/v2/sched/onesend

• Description: Creates a new one-time sending in future. Scheduler allows tuning the group of receivers via filters and choosing a moment for sending in future. No sending happens if scheduler has no attached pushes.

Request

curl --url "https://core.push.express/api/b/v2/sched/onesend"
    --request POST
    --header "content-type: application/json"
    --header "Authorization: Bearer ..."
    --data '
{
  "name": "Name of scheduler",

  "date": "2006-01-02",
  "time": "15:04",
  "local_time": false,
  "timezone": "-07:00",

  "all_apps": false,
  "app_ids_include": [
    123,
    234
  ],
  "app_ids_exclude": [
    345
  ],
  "app_groups_include": [
    1
  ],
  "app_groups_exclude": null,

  "all_countries": false,
  "countries_include": [
    "PT",
    "GB"
  ],
  "countries_exclude": [],

  "all_languages": true,
  "languages_include": [],
  "languages_exclude": [
    "pt"
  ],

  "all_audiences": false,
  "audiences_include": [
    "myaud1_1234",
    "myaud2_1234"
  ],
  "audiences_exclude": [
    "myaud3_1234"
  ],
  "audience_groups_include": [
    11,
    22
  ],
  "audience_groups_exclude": [
    33
  ],

  "event_include": ["install","reg"],
  "event_exclude": ["dep"],
  "external_ids": [
        "0b50bec7-ea47-437c-be5b-c4344bf0fc53",
        "b8c966b3-83be-44d5-a0f1-67faf45278e5"
]
}

Body params:

part 1, name

• name, required, string. Name of scheduler.

part 2, moment of sending

• date, required, string. Format YYYY-MM-DD

• time, required, string. Format HH-MM

• local_time, required, bool. "True" stands for "send by local time of devices", "false" stands for "send by one chosen timezone".

• timezone, required if local_time=false, excluded if local_time=true, string. Format +HH:MM. Offset of UTC.

part 3, filters, applications

• all_apps, optional, bool. Flag to include all applications into sending. If chosen True then app_ids_include and app_groups_include must be be omitted.

• app_ids_include, optional, list of int. List of application IDs to include into sending.

• app_ids_exclude, optional, list of int. List of application IDs to exclude from sending.

• app_groups_include, optional, list of int. List of application group IDs to include into sending. Make your application groups and manage them here

• app_groups_exclude, optional, list of int. List of application group IDs to exclude from sending.

If filters result in an empty set of applications then no scheduler is created. Corresponding _include and _exclude lists must have no common elements.

part 4, filters, countries

• all_countries, optional, bool. Flag to include devices with any country into sending. If chosen True then countries_include must be be omitted.

• countries_include, optional, list of int. List of countries to include into sending. Follow iso3166_1_alpha2 standard.

• countries_exclude, optional, list of int. List of countries to exclude from sending. Should be provided only if all_countries = true. Follow iso3166_1_alpha2 standard.

part 5, filters, languages

• all_languages, optional, bool. Flag to include devices with any language into sending. If chosen True then languages_include must be be omitted.

• languages_include, optional, list of int. List of languages to include into sending. Follow bcp47_language_tag standard.

• languages_exclude, optional, list of int. List of languages to exclude from sending. Should be provided only if all_languages = true. Follow bcp47_language_tag standard.

part 6, filters, audiences

In PushExpress audience is a tag that can be attached to devices. Some devices may have no audience.

Create audiences or segments here, create audience or segment groups here

• all_audiences, optional, bool. Flag to include all audiences into sending.

If flag is on then only devices with any audience defined will be reached out while devices with no audience will not be reached out.

If one wants to reach out to all devices regardless of audience they should set all_audiences to false and omit audiences_include with audience_groups_include.

If chosen True then audiences_include and audience_groups_include must be be omitted.

• audiences_include, optional, list of string. List of audiences to include into sending.

• audiences_exclude, optional, list of int. List of audiences to exclude from sending.

• audience_groups_include, optional, list of int. List of audience group IDs to include into sending.

• audience_groups_exclude, optional, list of int. List of audience group IDs to exclude from sending.

Corresponding _include and _exclude lists must have no common elements.

part 7, filters, events

Here you can specify both system events: install, reg, dep, and custom ones. The installation includes all devices, reg - only registered ones, dep - those who have replenished the balance at least once. Custom events can be created here. More information about the events is here.

• event_include, optional, list of string. Filters devices which had this event in history. If field is not provided it will be set to install i.e. devices are to be chosen regardless of event happened.

• event_exclude, optional, list of string. Filters devices which did not have this event in history. If field not provided devices are to be chosen regardless of event that did not happen.

part 8, filters, external id

You can only send to certain devices by transmitting their Extrenal IDs.

You can view the device ID in the devices section here in the ExternalUserId field. Make sure that you have configured the creation of an ExternalUserId when implementing the sdk.

• external_ids, optional, list of string. List of external IDs devices.

Response:

• 201: New one-time sending in future created

{"id":12345}

• id, int. ID of newly created one-time sending.

No sending happens if scheduler has no attached pushes.

Next step

To create push, refer to the Push Creation API.

To attach push to the scheduler, refer to the Push Attachment API.

---

Get a OneSend Scheduler

GET https://core.push.express/api/b/v2/sched/onesend/:sched_id

• Description: Retrieves details of a specific scheduler by its ID.

Request

curl --url "https://core.push.express/api/b/v2/sched/onesend/:sched_id"
    --request GET
    --header "Authorization: Bearer ..."

---

Response

• 200

{
  "id": 14194,
  "name": "One Sned API",
  "date": "2025-05-28",
  "time": "13:02",
  "local_time": false,
  "timezone": "+00:00",
  "app_ids_include": [
    33337,
    35593,
    35897,
    37613,
    37809,
    39026
  ],
  "app_ids_exclude": null,
  "app_groups_include": [],
  "app_groups_exclude": [],
  "all_apps": false,
  "all_countries": false,
  "all_languages": false,
  "all_audiences": true,
  "countries_include": null,
  "countries_exclude": null,
  "languages_include": null,
  "languages_exclude": null,
  "event_include": "install",
  "event_exclude": "",
  "audiences_include": null,
  "audiences_exclude": null,
  "audience_groups_include": [],
  "audience_groups_exclude": [],
  "external_ids": null,
  "archived": false
}

---

Error handling

All HTTP response codes 2xx SHOULD be considered as success. Requested action was executed successfully.

All HTTP response codes above 400 MUST be considered as error. Requested action failed. Retries policy should be hold according to HTTP specification.

Common API errors:

• 400 - request error. Request has invalid data. Check you request (url, headers, payload)

• 401 is returned when provided API token is invalid. Check your authentification data.

• 403 is returned when access to resource for current user is denied.

• 404 is returned when resource doesn't exist. Check your request data.

  Example: PUT https://core.push.express/api/b/v2/sched/:sched_type/:sched_id/pushes returns 404 when provided sched_id doesn't exist

• All HTTP response codes 5xx - other errors from proxy servers, load balancers, etc. There may or may not have some explanation in response body. These errors always require retries.

API errors have content-type: application/json header and json response body

Example: {"error": "validation error: ...", "req_id":"<string>"}

Response parameters:

• req_id string is a request ID. It is used by support for problem solving, please, provide it to support if problem emerged.

• error object, describing errors.

Non-API errors like 502, 504, etc., may or may not include a description.