Docs
Go

Core Concepts

Getting Started

PushFire models engagement around project-scoped primitives that appear across the console sidebar and APIs. Every subscriber, tag, segment, workflow, broadcast, connector, and layout belongs to exactly one project.

Project

A project is your isolated workspace. It stores audience data, messaging automations, delivery configuration, and team access. Projects are created with Firebase credentials so PushFire can send push notifications on your behalf.

  • Pushfire ID — the project UUID shown on Overview; copy it for API calls and integrations
  • Firebase configuration — uploaded as an encrypted Service Account JSON under Settings → General
  • Plan & billing — subscription status visible on Overview (Owners only for Payment & Billing)

Subscriber

A subscriber represents an end user tracked inside a project. Subscribers are the unit workflows and broadcasts operate on.

  • externalId — your app's user identifier (optional)
  • name, email, phone — profile and contact fields
  • metadata — arbitrary JSON (strings, numbers, booleans, nested objects)
  • tags & segments — audience membership used for targeting and automation

The subscribers list supports filtering by all, identified, or anonymous users. Subscribers enter PushFire inbound via SDK or API.

Device

Each subscriber can register one or more devices for push delivery. A device stores an FCM token, platform, and push preferences.

  • Platforms — Android, iOS, Web, Desktop, or Other
  • fcmToken — Firebase Cloud Messaging token used for delivery
  • pushNotificationEnabled — whether the device accepts push messages
  • lastActiveAt — last activity timestamp for the device

Workflow push nodes can target Web, Android, iOS, or All Platforms.

Tag

Tags are named labels attached to subscribers—manually, through workflows, or via API. Tags can be Custom or Default, and can be active or inactive.

Tags power segments, workflow Condition nodes, Wait (Tag) nodes, and broadcast targeting. Default tags are read-only in the console.

Tag operators

Segments and workflow nodes evaluate tags using these operators:

  • Exists / NotExists — subscriber has (or lacks) the tag
  • Equals / NotEquals — tag value comparison
  • Contains / NotContains — string containment on tag value
  • GreaterThan / LessThan — numeric comparison on tag value

Segment

Segments are rule-based audience groups built from tag conditions. They can be Custom or Default. When syncSubscribers is enabled by the platform, the console shows a sync indicator while membership is kept up to date automatically.

Each segment is a set of tag conditions using the tag operators above. Default segments are read-only in the console.

In workflow Condition nodes, segment checks use Exists / NotExists to test whether a subscriber is currently in a segment.

Segments are used in three ways:

  1. Audience targeting — filter and analyze subscribers in the console
  2. Broadcasts — send one-off campaigns to matching subscribers
  3. Workflow triggers — Entry Segment workflows start when a subscriber joins a segment

Workflow

Workflows are visual automations built in the React Flow editor. Each workflow has a trigger type, a versioned graph of nodes and edges, an active/inactive flag, and execution history.

Trigger types

  • Entry Segment — starts automatically when a subscriber enters the configured segment
  • Manual — triggered via API when your app sends a manual workflow event

Node types

  • Start — entry point of the graph
  • Wait — pause by Time (minutes, hours, days) or until Tag conditions are met
  • Condition — branch on Tags or Segments (true/false paths)
  • Push Notification — send push with title, body, and platform filter
  • Email Notification — send email via connector, sender, layout, subject, and HTML body
  • Join — rejoin branches after a Condition node (added automatically by the graph editor)
  • End — terminate the path (structural; not added from the node menu)

Email nodes require an active email connector, a sender, and a published email layout. Workflow versions are immutable—edits create a new version while preserving execution history.

Executions

When a workflow runs, the console tracks execution and per-subscriber progress:

  • Execution status — Pending, InProgress, Waiting, Stopped, Completed, or Failed
  • Per-subscriber tasks — which node each subscriber is on
  • Per-device delivery — push delivery status per device

Broadcast

Broadcasts are one-off push or email campaigns—no workflow graph required. Find them under Messaging → Broadcast.

Targeting

Both push and email broadcasts support three target types:

  • tag — all subscribers with the selected tag(s)
  • segment — all subscribers matching segment rules
  • subscriber — specific individuals

Status lifecycle

Each broadcast moves through Pending → InProgress → Completed (or Failed / Retrying). The console shows totalSubscribers, completedCount, and failedCount per campaign.

Email broadcasts additionally require a connector, sender, layout, subject, and HTML body.

Connector

Connectors link PushFire to external delivery providers. Configure them under Connectors (Owner and Editor only).

  • Email — Resend (available today); Mailchimp and SendGrid are coming soon
  • SMS — Twilio (coming soon)

Each connector has a name, encrypted credentials, configuration (such as email domain), and an isActive flag. Email connectors also define senders (from-address identities).

Email workflows, Emails → Layouts, email broadcasts, and email API messages all require an active email connector with at least one sender configured.

Email layout

Layouts live under Emails → Layouts (Owner and Editor, requires email connector). Each layout has a name, HTML header, and HTML footer.

Workflow email nodes and email broadcasts supply the body HTML sandwiched between the layout header and footer. Layouts must be published before they can be used in workflows or broadcasts.

API Token and API Messages

Under Developers (Owner and Editor), your backend can send messages programmatically:

  • API Token — project-scoped Bearer token for REST API authentication (regeneratable)
  • API Messages → Push — one-off programmatic push sends
  • API Messages → Email — one-off programmatic email sends (requires email connector)
  • API Reference — external link to the full REST API docs

API Messages are outbound like broadcasts, but triggered by your backend instead of the console UI.

Roles and access

Every project member has one of three roles:

  • Owner — full access including Payment & Billing
  • Editor — configure messaging, audience, connectors, developers tools, and general settings
  • Viewer — read-only access to dashboards, broadcasts, and audience lists

Console permission matrix

  • Getting Started, Overview, Messaging, Audience — all roles (Viewers are read-only)
  • Connectors, Emails, Developers — Owner and Editor only
  • Settings → General — Owner and Editor only
  • Settings → Payment & Billing — Owner only
  • Settings → Members — all roles (Viewers cannot invite or change roles)

Viewers cannot edit general settings or manage billing. Only Owners access Payment & Billing.

Inbound vs outbound

  • Inbound (Integrations) — your app or backend sends subscribers, tags, devices, and events into PushFire via SDK or API
  • Outbound (Connectors, Broadcasts, Workflows, API Messages) — PushFire delivers push notifications and emails to your audience

Data flows in through integrations; delivery goes out through Firebase (push) and connectors (email). Keep this distinction in mind when reading Integrations and Connectors.