Transactional vs Marketing Push Notifications

An order confirmation and a weekend sale share an API and nothing else. This reference sets out the operational split — queues, headers, caps, consent basis and VAPID identity — and shows what breaks when both classes run through one pipeline.

The Split at a Glance

Everything below is an elaboration of one rule: the two classes must not share a code path that can decide to drop a message.

Two Lanes, One Push Service

Both classes eventually make the same HTTP request to the same push service. What differs is everything upstream of that request: which queue holds the job, which gates it passes, and what headers it carries.

The queues need genuinely different characteristics. A transactional queue is shallow, has aggressive per-job retry with jitter, and alerts when depth exceeds a handful of seconds’ worth of work. A marketing queue is deep by design, sheds load gracefully, and is expected to take minutes to drain — the batching and concurrency choices are covered in message batching and throughput optimization.

Urgency, TTL and Topic

RFC 8030 gives you three request headers that encode intent to the push service, and the correct values differ sharply by class.

Urgency tells the push service how much it may delay delivery to save the device’s battery. A device on a metered connection or in a low-power state may hold low and very-low messages until it next wakes. Use high for a two-factor prompt or a payment failure; normal for a shipping update; low for a campaign. Marking everything high does not make delivery faster in aggregate — it removes the signal the push service uses to protect the user’s battery, and it is the sort of thing providers notice.

TTL is how long the push service should keep trying before discarding. The right value is the moment the message stops being true. A “your code is 402 913” push has a TTL of five minutes because the code expires. A flash-sale push has a TTL of a few hours because the sale ends. A digest has a TTL of a day. The failure mode of a too-long TTL — a message arriving long after it made sense — is covered in TTL 0 vs TTL 86400 delivery guarantees.

Topic makes the push service replace an undelivered message with a newer one carrying the same topic. Scope it per entity for transactional messages — one topic per order, so “shipped” replaces “packed” if the device was offline — and per campaign for marketing, so a subscriber who was offline all day gets today’s digest and not last Tuesday’s.

Payload rules are identical for both classes: the ciphertext is capped at 4 KB and must use the aes128gcm content encoding from RFC 8291, so both lanes send ids and a URL rather than rendered content.

import webpush from 'web-push';

const PROFILES = {
  transactional: { urgency: 'high', ttl: 3600, subject: 'mailto:ops@example.com' },
  marketing:     { urgency: 'low',  ttl: 43200, subject: 'mailto:marketing@example.com' }
};

export async function send(kind, sub, payload, topic) {
  const p = PROFILES[kind];
  if (!p) throw new Error(`unknown notification class: ${kind}`);
  webpush.setVapidDetails(p.subject, process.env.VAPID_PUBLIC_KEY, process.env.VAPID_PRIVATE_KEY);
  return webpush.sendNotification(sub, JSON.stringify(payload), {
    TTL: p.ttl,
    urgency: p.urgency,
    topic                                   // 'order-9f2a' or 'camp-spring-sale'
  });
}

Note that the VAPID subject differs while the key pair stays the same. The subject is the contact a push service operator uses when something is wrong with your traffic, so pointing marketing volume at a marketing owner and transactional volume at on-call is straightforwardly useful. If you genuinely want separate key pairs — some teams do, to isolate reputation — remember that each key pair implies a separate subscription, so a subscriber must subscribe twice; the mechanics and the migration cost are covered in VAPID key generation and rotation. Whichever route you take, the keys come from process.env.VAPID_PUBLIC_KEY and process.env.VAPID_PRIVATE_KEY and are never committed.

What Goes Wrong in a Single Pipeline

The classic incident: a subscriber gets three campaign notifications during the day, hits the daily frequency cap, then places an order in the evening. The receipt enters the same queue, hits the same cap check, and is silently discarded. Support hears about it a week later as “I never got my confirmation”.

The same shared-pipeline shape produces three more failures worth naming. A campaign backlog of 400,000 jobs sits in front of the receipt, so it arrives forty minutes late. Quiet hours suppress a fraud alert at 23:40. A subscriber who opted out of marketing stops receiving password-reset notifications, because one boolean governed both.

Every one of these is fixed by classification at the entry point rather than by conditionals deeper in the stack. Make the class a required, non-defaulting argument, and make the cap check physically unreachable from the transactional path.

// entry point — the class is required and drives routing
const CLASSES = new Set(['transactional', 'marketing']);

export async function enqueue({ kind, subscriberId, payload, topic }) {
  if (!CLASSES.has(kind)) throw new Error('notification class is required');

  if (kind === 'transactional') {
    return queues.tx.add('send', { subscriberId, payload, topic }, {
      attempts: 8, backoff: { type: 'exponential', delay: 500 }, priority: 1
    });
  }

  const allowed = await capGate.check(subscriberId);          // marketing only
  if (!allowed.ok) {
    metrics.increment('push.marketing.suppressed', { reason: allowed.reason });
    return null;
  }
  return queues.mkt.add('send', { subscriberId, payload, topic }, {
    attempts: 3, backoff: { type: 'exponential', delay: 5000 }, priority: 10
  });
}

Cap design itself — window, counter storage, per-category budgets — is covered in setting push notification frequency caps. The point here is only where the gate is allowed to live.

Consent Basis: Contract Versus Consent

Under GDPR the two classes rest on different legal bases, and the difference is not cosmetic — it determines what an opt-out must do.

Marketing push relies on consent: freely given, specific, informed, unambiguous, and as easy to withdraw as it was to give. That means a granular preference surface, an immediate effect on withdrawal, and a stored record of when and how consent was captured. The permission grant in the browser is not, by itself, that record; it proves the user allowed notifications, not that they agreed to marketing.

Transactional push relies on contract (performing a contract the user is party to) or on legitimate interest for things like security alerts. A shipping notification is part of delivering the order; it is not marketing and does not need marketing consent. It also, critically, must not be suppressed by a marketing opt-out — withholding an order confirmation because someone unsubscribed from a newsletter is a service failure dressed up as compliance.

Practical consequences for the preference surface, which should follow the patterns in opt-out and preference centres:

• Present marketing categories as individually togglable, and show transactional notifications as a separate, non-togglable list with an explanation of why.
• Store the class on every send record. When someone exercises a data-subject request you need to say which messages were sent on which basis.
• On marketing withdrawal, suppress marketing immediately and leave the push subscription itself intact. Only a full account closure or a browser-level permission revocation should end transactional delivery.
• Keep the consent timestamp, the wording shown, and the version of that wording. “The user clicked allow” is not a defensible record on its own.

Gotchas & Edge Cases

• A receipt with a promo code is marketing. If you want to upsell, send the receipt transactionally and the offer as a separate marketing send. Merging them puts the receipt behind the consent gate.
• Do not exempt transactional from quiet hours reflexively. A 03:00 “your subscription renewed” push is technically transactional and still a bad notification. Exempt genuinely urgent classes; queue the rest until morning.
• Alerting differs. A failed transactional send needs a fallback channel and a page. A failed marketing send needs a counter. Wiring both to the same alert policy produces either noise or silence.
• Watch the Topic collision. Two order updates for different orders must not share a topic, or one silently replaces the other in the push service queue.
• Split the dashboards. Blending both classes into one click-through number is meaningless — transactional click-through is structurally several times higher and will mask everything happening to campaigns.
• Breaking-news alerts are their own class. They are neither contract-based nor ordinary marketing; they need their own consent category and their own fan-out design, as described in breaking-news push alert architecture.

Related

• Back to Web Push Use-Case Playbooks — the campaign patterns that sit on top of this pipeline split.
• Cart abandonment push notifications — a triggered send that is marketing despite feeling transactional.
• Setting push notification frequency caps — the gate that must only ever sit on the marketing lane.
• TTL 0 vs TTL 86400 delivery guarantees — how the TTL you pick per class changes what the push service does with an offline device.

FAQ