Send notification

POST https://api.xulo.io/api/v1/notifications

Sends a push to one app. Without send_after the send starts at once and finishes in the background. With send_after it sends when that time arrives. There is no approval step.

Request#

Headers:

Body:

Name exactly one target: included_segments, tag, include_subscription_ids or include_external_ids. None, or more than one, returns 422.

The default language is en when contents has it, otherwise the first language in contents. Each device gets its own language when there is a match. See Notifications.

Example#

curl https://api.xulo.io/api/v1/notifications \
  -H "Authorization: Key $XULO_REST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "headings": {"en": "Your order shipped"},
    "contents": {"en": "It arrives tomorrow.", "tr": "Yarın teslim edilecek."},
    "include_external_ids": ["USER_ID"],
    "url": "exampleapp://orders/1",
    "data": {"order": "1"}
  }'

<?php

$payload = [
    'app_id' => 'YOUR_APP_ID',
    'headings' => ['en' => 'Your order shipped'],
    'contents' => ['en' => 'It arrives tomorrow.', 'tr' => 'Yarın teslim edilecek.'],
    'include_external_ids' => ['USER_ID'],
    'url' => 'exampleapp://orders/1',
    'data' => ['order' => '1'],
];

$curl = curl_init('https://api.xulo.io/api/v1/notifications');
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Key '.getenv('XULO_REST_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$result = json_decode(curl_exec($curl), true);

use Illuminate\Support\Facades\Http;

$result = Http::withHeaders([
        'Authorization' => 'Key '.config('services.xulo.rest_key'),
    ])
    ->post('https://api.xulo.io/api/v1/notifications', [
        'app_id' => 'YOUR_APP_ID',
        'headings' => ['en' => 'Your order shipped'],
        'contents' => ['en' => 'It arrives tomorrow.', 'tr' => 'Yarın teslim edilecek.'],
        'include_external_ids' => ['USER_ID'],
        'url' => 'exampleapp://orders/1',
        'data' => ['order' => '1'],
    ])
    ->throw()
    ->json();

const response = await fetch("https://api.xulo.io/api/v1/notifications", {
  method: "POST",
  headers: {
    Authorization: `Key ${process.env.XULO_REST_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    app_id: "YOUR_APP_ID",
    headings: { en: "Your order shipped" },
    contents: { en: "It arrives tomorrow.", tr: "Yarın teslim edilecek." },
    include_external_ids: ["USER_ID"],
    url: "exampleapp://orders/1",
    data: { order: "1" },
  }),
});

const result = await response.json();

import os
import requests

response = requests.post(
    "https://api.xulo.io/api/v1/notifications",
    headers={"Authorization": f"Key {os.environ['XULO_REST_KEY']}"},
    json={
        "app_id": "YOUR_APP_ID",
        "headings": {"en": "Your order shipped"},
        "contents": {"en": "It arrives tomorrow.", "tr": "Yarın teslim edilecek."},
        "include_external_ids": ["USER_ID"],
        "url": "exampleapp://orders/1",
        "data": {"order": "1"},
    },
    timeout=10,
)
response.raise_for_status()
result = response.json()

In Laravel, config('services.xulo.rest_key') stands for wherever your app keeps the key.

Response#

Every call answers before Apple is called. The status code depends on the target.

A segment or a tag#

A send to included_segments or tag with someone in its audience returns 202 Accepted. The send is recorded, and Xulo sends it in the background:

{
  "id": 43,
  "status": "queued",
  "sent": 0,
  "failed": 0,
  "skipped": 0,
  "estimate": 1200,
  "message": "Queued for 1200 devices. It sends in the background."
}

Xulo splits the audience into chunks of 500 devices and sends them one after another. Read the progress with Notification stats: status moves from queued to sending, then to approved, or to draft if Apple accepted none of the devices.

One send reaches at most 1,000,000 devices. A larger audience returns 422 with "This send reaches 1,200,000 devices. One send reaches at most 1,000,000." and nothing is sent.

A list of ids#

A send to include_subscription_ids or include_external_ids returns 200:

{
  "id": 42,
  "status": "sending",
  "sent": 0,
  "failed": 0,
  "skipped": 0,
  "estimate": 1,
  "message": "Sending to 1 device."
}

Fields#

Check status and sent, not only the HTTP status. A call that reached nobody still returns 200. A queued or sending call has not reached anyone yet.

Throttling a send#

throttle_rate_per_minute spreads a segment or tag send over time. With "throttle_rate_per_minute": 1000, the chunks are spaced so that about 1,000 devices get it each minute. Without it, the chunks go out one after another with no pause.

It applies to a segment or tag send made now or at a set time. A list of ids and a send with delayed_option: "timezone" do not use it. A value that is not a whole number from 1 to 100,000 returns 422.

Retrying safely#

Send an Idempotency-Key header, or idempotency_key in the body, and a retry of the same call does not send twice. A repeat within 24 hours returns the first response with the header Idempotent-Replay: true. A repeat while the first call is still being handled returns 409. The same key with a different body returns 422. See Idempotency.

Delivery paused#

If the app has an invoice past its due date, the call returns 402 with "Delivery is paused until the invoice for this app is paid." Nothing is recorded or sent.

If that happens while a segment or tag send is going out, the devices not reached yet are never sent, not even after the invoice is paid. The send ends as approved when some devices got it, or as draft when none did. See Notification stats.

Errors are listed on Errors.