Natom API

Integrate push into your systems: campaign sending, site management and statistics over HTTP. Available from the Pro plan.

Authentication

Generate your key from the dashboard: Plan → API → Generate key. Every request passes it as a bearer token:

Authorization: Bearer nk_live_xxxxxxxx...

Base URL: https://api.natom.app. All requests and responses are JSON. The key grants access to your account resources (sites, campaigns, audiences, statistics); it cannot touch billing or account settings.

Treat the key like a password: if compromised, regenerate it from the dashboard (the old one stops working immediately).

Main endpoints

GET /api/sites

Your sites with active subscriber counts.

curl https://api.natom.app/api/sites \
  -H "Authorization: Bearer nk_live_..."

POST /api/campaigns

Creates (and optionally sends) a campaign. The typical use case: your CMS publishes an article and calls this endpoint.

curl -X POST https://api.natom.app/api/campaigns \
  -H "Authorization: Bearer nk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "siteIds": [12],
    "title": "Your push title",
    "body": "The notification body",
    "url": "https://yoursite.com/article",
    "imageUrl": "https://yoursite.com/cover.jpg",
    "segmentId": 34,
    "send": true
  }'

Field	Type	Notes
siteIds	int[]	one or more sites (same push to all). With multiple sites, no segmentId
title, body, url	string	required
iconUrl, imageUrl	string	optional
segmentId	int	send to a single audience only (single site)
scheduledAt	ISO 8601	future scheduling; mutually exclusive with send:true
ttlSeconds	int	delivery expiry, default 86400
send	bool	true = sends immediately; false = draft

POST /api/campaigns/:id/send

Sends a draft or fast-forwards a scheduled campaign.

GET /api/campaigns/:id

Status and statistics of a campaign: impressions_est (sampling-based estimate), clicks, status.

GET /api/campaigns

The account's latest 200 campaigns, with domain and statistics.

GET /api/sites/:id/segments

The site's audiences with member counts (to find the segmentId for targeted sends).

GET /api/stats?days=30

Day-by-day subscriber growth, summary tiles, breakdowns by country, device, browser and OS, members per audience.

WordPress

The Natom Push plugin uses two dedicated endpoints, designed for people working inside the editor who do not know internal IDs: the site is resolved from its domain.

The plugin does not use the API key described on this page: it uses a dedicated key (nw_...) included in every plan, valid only for the two endpoints below. Generate it from the dashboard: Sites › Code › WordPress panel, where you also download the plugin.

GET /api/wp/context

Lists the account's sites with their audiences. The plugin settings page uses it to verify the key and fill the menus.

POST /api/wp/push

Sends a notification immediately. The site is resolved from the domain field or, if missing, from the URL host (a www. prefix is ignored).

{
  "title": "Notification title",
  "body": "Notification text",
  "url": "https://yoursite.com/article",
  "domain": "yoursite.com",
  "imageUrl": "https://yoursite.com/image.jpg",
  "segment": "News"
}

Target an audience with segmentId or with segment (its name, case-insensitive). Without an audience the push goes to every subscriber of the site.

Responses and errors

Standard codes: 200 ok, 400 invalid parameters, 401 missing or revoked key, 403 resource not yours or endpoint unavailable via API, 404 not found. The error body is {"error": "description"}.

Good practices

Send idempotency: create the campaign with send:false, verify the response, then call /send. You avoid double sends on retries.
For automatic pushes from a CMS, consider automatic RSS first: zero code, same result.
Impression statistics are sampled by design: use impressions_est, not the raw field.

Need an endpoint that is missing? Write to support@natom.app.