Skip to main content

Import subscribers

Subscriptions › Import (admin role) takes a CSV of up to 150 MB and writes the rows into subscriptions through exactly the path the SDK's subscribe call uses: the same token is updated rather than duplicated, external_id attaches the device to its user (creating the user if needed), tags merge. The file is parsed once and not kept. The browser gzips it before upload (a .csv.gz is accepted as is), so a 150 MB export stays under the 100 MB request limit of a proxy such as Cloudflare. The upload is one request, so behind Traefik raise its 60-second read timeout (see Dokploy).

The import page

Two formats:

OneSignal — Export Users. Both files OneSignal has produced over the years are accepted; the header tells them apart.

  • Users export (current, users_export_onesignal_users_….csv): push_token, channel (iOS, Google Android; Huawei rows carry no FCM token and web rows carry no keys, both are skipped), subscribed (Yes/No → opted in/out), external_id, language_code, timezone_id, country, email, phone_number, tags (JSON), app_version, device (model and OS version in one cell), first_session (kept as createdAt), last_active, unsubscribed_at (kept as the opt-out time for No rows), sessions, usage_duration, ip_address, lat/lon (0,0 means unknown), rooted, sdk_version, and the player_id / onesignal_id pair, kept under imported for cross-referencing. Nothing OneSignal knew about the device is dropped.
  • Players export (legacy): identifier (token, or the web endpoint), device_type (0 iOS, 1 Android, 5 Chrome, 7 Safari, 8 Firefox, 14 Edge — email, SMS and other rows are skipped), web_p256 / web_auth, external_user_id, language, timezone_id, country, tags (JSON), notification_types (-2 imports as opted out), invalid_identifier (true is skipped), last_active and created_at (unix seconds, kept), plus ip, lat/long, session_count, usage_duration, rooted, sdk and id.

Session and usage counters seed the row on first import and are left alone afterwards, so the SDK's first ping continues from where OneSignal stopped. Email and phone are stored on the user (we do not deliver on them) so a later export or segment still has them.

Generic. The columns our own export writes:

platform,token,endpoint,p256dh,auth,external_id,language,timezone,country,tags,opted_in,app_version,os_version,device_model,created_at,last_active_at,email,phone,sessions,usage_duration,ip,lat,lon,rooted,opted_out_at

platform is required; token for iOS/Android, endpoint + p256dh + auth for web; tags a JSON object; opted_in true/false; dates ISO. Everything after last_active_at is optional: phone in E.164, sessions and usage_duration (seconds) whole numbers, rooted true/false, opted_out_at only read when opted_in is false. The page shows the list.

The upload returns as soon as the header checks out; the rows are written in the background and the page polls the job every couple of seconds (you can leave and come back — the URL carries the job id). A full OneSignal export of ~350K rows takes about a minute. The result card counts rows, created, updated and skipped, and lists the first 100 bad rows by line number with the validation message. Re-running the same file updates instead of duplicating. Imported rows carry source: "csv_import"; no session is counted for them and their lastActiveAt is the file's, so an import does not make a dormant audience look alive.

After importing, send a small campaign and read the report's Failure reasons: dead tokens are invalidated on the way through, and that table tells you how much of the export was already gone. See Migrating from OneSignal.