PushizoDocs
OperationsRunbooks

Data export / import

The export/import jobs introduced in Phase 8 run in the worker on the maintenance queue; files are kept in S3-compatible object storage (RustFS locally, S3_* environment variables). Dashboard: Audience → Export / Import. API:…

The export/import jobs introduced in Phase 8 run in the worker on the maintenance queue; files are kept in S3-compatible object storage (RustFS locally, S3_* environment variables). Dashboard: Audience → Export / Import. API: POST/GET /v1/apps/{app_id}/exports, POST/GET /v1/apps/{app_id}/imports (admin scope).

Export

TypeColumns
usersid, external_id, tags (JSON), properties (JSON), session_count, first_seen_at, last_active_at, created_at — segment audience via filters.segment_id
subscriptionsid, user_id, external_id, channel, status, token_masked (last 8), device (JSON), test_device, last_active_at, unsubscribed_at, created_at — filters.channel, filters.status
eventsid, user_id, subscription_id, name, properties (JSON), value, source, occurred_at — filters.name, from, to
deliveriesid, message_id, campaign_id, subscription_id, user_id, channel, status, error_code, suppression_reason, sent_at, delivered_at, opened_at, clicked_at, created_at — filters.message_id, campaign_id, status, from, to
  • The file is a CSV with a UTF-8 BOM (for Excel compatibility); cells starting with =, +, -, @ are neutralized with a leading single quote.
  • The upper limit is 1,000,000 rows; rows are read in batches of 5,000 with keyset pagination. Measured: 100,000 users ≈ 2 s (18 MB).
  • GET …/exports/{id} returns a download_url for a completed job (signed, EXPORT_URL_TTL_HOURS, default 24 hours). The address given to the browser is determined by S3_PUBLIC_ENDPOINT. This address cannot contain a path prefix (the SigV4 signature covers the path and Host); compose production uses a separate domain: STORAGE_HOST (nginx forwards only GET/HEAD, Host is preserved) and S3_PUBLIC_ENDPOINT=https://<STORAGE_HOST>.
  • Tokens are never exported raw (they are masked); if PII such as email/phone is added in the future, the same masking applies.

Import

The POST …/imports body is multipart/form-data: type (csv_users | legacy_players) and file (CSV, up to 50 MB). When the job completes, it returns stats (processed, created_users, updated_users, created_subscriptions, skipped, errors) and, for failed rows, an error_report_url (columns: line, error, row).

Pushizo CSV (csv_users)

ColumnDescription
external_idUser ID (required if there is no subscription). When the same external_id repeats, tags/properties are merged.
channelios_push, android_push, email, sms (required if a token is present; web_push cannot be imported via CSV: there are no p256dh/auth keys)
tokenDevice token / email / phone; (app, channel, token) is unique and is updated if it already exists
statussubscribed (default), unsubscribed, invalid
language, timezoneproperties.language and device.timezone (IANA)
tagsA JSON object, or tag.<key> columns
propertiesA JSON object, or property.<key> columns

Example:

external_id,channel,token,language,timezone,tag.plan,tag.city
u-1001,ios_push,0a1b2c…,tr,Europe/Istanbul,pro,Ankara
u-1002,,,en,,free,

Legacy provider player CSV (legacy_players)

Upload the "Export" file from the legacy provider's dashboard as is. Mapping:

Legacy providerPushizo
external_user_idexternal_id (if empty and a token is present, an anonymous user)
identifiertoken
device_type 0 → ios_push; 1, 2, 13 → android_push; 5, 7, 8, 9, 10 → web (user only); 11 → email; 14 → sms
invalid_identifier = tsubscription invalid
notification_types < 0subscription unsubscribed
tags (JSON)tags
languageproperties.language, device.locale
timezone (seconds from UTC)device.timezone = Etc/GMT∓h (empty if not a whole hour)
device_model, device_os, game_versiondevice.model, device.os_version, device.app_version
session_count, created_at, last_activesession_count, first_seen_at, last_active_at

Sample file: tests/fixtures/legacy-players-sample.csv. Import is idempotent: when the same file is uploaded a second time, users/subscriptions are not duplicated (updated_users increases).

Troubleshooting

  • If the job is failed, check the error field; if storage is unreachable, the warning "Nesne depolama erişilemedi" (object storage unreachable) is logged at API startup (npm run infra:status → rustfs).
  • Keep large import files under 500k rows (IMPORT_MAX_ROWS); split larger files and upload them in parts.

On this page