canonical: https://jentic.com/apis/niftyimages.com/niftyimages

# NiftyImages API

Jentic publishes the only available OpenAPI specification for NiftyImages API, keeping it validated and agent-ready. NiftyImages is an email-marketing service that generates personalised images, countdown timers, dynamic maps, and Photoshop-driven graphics rendered at open time inside an email. The REST API lets developers list and delete images, manage data store records that drive personalisation, update countdown timers, edit map locations, suspend Bee Plugin and Widget end users, and pull aggregated stats. Authentication is by ApiKey (header or query) or HTTP Basic, the same key issued from a NiftyImages account.

## For AI agents

Manage NiftyImages personalised email images, data stores, countdown timers, maps, and end users across 27 endpoints under api.niftyimages.com.

## Scope

Does not handle email sending, list management, or template editing - use for NiftyImages personalised image, data store, timer, and map operations only.

## Capabilities

- Page through and inspect personalised images on the account through `/v1/Images`
- Pull aggregated open and click stats through `/v1/Images/stats`
- Add or delete records in a personalisation data store through `/v1/DataStores/{storeKey}/records`
- Reschedule a countdown timer's target date through PUT `/v1/Timers/{timerKey}`
- Add, update, or delete map locations through `/v1/Maps/{mapKey}/locations`
- Suspend Bee Plugin or Widget end users through `/v1/BeePlugin/users/{userId}/suspend` and `/v1/Widgets/{widgetKey}/users/{userId}/suspend`
- Inspect per-user widget stats and image lists through `/v1/Widgets/{widgetKey}/users/{userId}/stats` and /images

## Use cases

### Personalisation data store sync

Email marketers can keep a NiftyImages data store in sync with their CRM by pushing new or updated rows whenever a contact changes. POST `/v1/DataStores/{storeKey}/records` adds a record, DELETE `/v1/DataStores/{storeKey}/records/{recordId}` removes one, and GET `/v1/DataStores/{storeKey}/fields` returns the field schema so the agent always sends the right column names.

Example prompt: POST a record to `/v1/DataStores/customers/records` with fields {first_name: 'Sam', tier: 'gold'} and confirm it appears in GET `/v1/DataStores/customers/records.`

### Countdown timer scheduling

Promotional emails often use NiftyImages countdown timers that render a fresh image at open time. PUT `/v1/Timers/{timerKey}` updates the target date, so an agent can roll the same timer asset forward through a sequence of campaigns instead of creating a new one each time.

Example prompt: PUT `/v1/Timers/black-friday-2026` with the new target date 2026-11-27T05:00:00Z and verify the response confirms the update.

### Dynamic store-locator maps in email

Brands with physical stores can render a personalised map in each recipient's email by maintaining a NiftyImages map of locations. POST `/v1/Maps/{mapKey}/locations` adds a store, PUT updates one, DELETE retires a closure, and GET `/v1/Maps/{mapKey}/locations/search` returns nearest matches for a given postcode at send time.

Example prompt: POST a new location with name 'Brighton Pier Cafe' and lat/lng coordinates to `/v1/Maps/cafes/locations.`

### AI agent email personalisation operations

An AI agent running an email marketing playbook can push fresh personalisation data, swap in a new countdown timer, and pull image performance stats across an entire campaign. Through Jentic, the agent searches by intent and Jentic returns the right NiftyImages endpoint with its schema. The ApiKey header value is held in the vault and never enters the agent's chat context.

Example prompt: Search Jentic for 'add a record to a data store', load POST `/v1/DataStores/{storeKey}/records`, and execute it for storeKey=loyalty with fields email and points.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/Images` | Page through images on the account |
| GET | `/v1/Images/stats` | Get aggregated image stats |
| POST | `/v1/DataStores/{storeKey}/records` | Add a record to a personalisation data store |
| DELETE | `/v1/DataStores/{storeKey}/records/{recordId}` | Delete a single data store record |
| PUT | `/v1/Timers/{timerKey}` | Update a countdown timer's target date |
| POST | `/v1/Maps/{mapKey}/locations` | Add a location to a map |
| GET | `/v1/Maps/{mapKey}/locations/search` | Search a map for nearby locations |
| PUT | `/v1/BeePlugin/users/{userId}/suspend` | Suspend a Bee Plugin user |

## Key resources

- **Images** — Page through images, get details, delete, and read aggregated stats
- **Data Store** — Manage personalisation records and field metadata for a data store
- **Timers** — Update the target date on countdown timers
- **Maps** — Manage map definitions and individual map locations
- **Widgets** — Read widget stats, list users, and suspend offending users
- **Bee Plugin** — List Bee Plugin users, view their images, and suspend access
- **Photoshop** — Manage Photoshop-driven personalised image assets

## Why Jentic

- **Setup:** Wiring NiftyImages by hand means picking between its ApiKey header, ApiKey query, or basic auth, and building requests against its host yourself. Through Jentic you install once, import the NiftyImages API from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** NiftyImages puts the store key in the URL path (`/v1/DataStores/{storeKey}/records/...`), so a rule can pin your agent to one data store: it can add and read records for that store and nothing else. You choose the operations it may call, so destructive ones like deleting a record or suspending a BeePlugin user are not included unless you add them.
- **Credential handling:** Your NiftyImages API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'add a record to a data store' or 'add a location to a map', and Jentic returns the matching NiftyImages operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Bannerbear API** — Bannerbear is a more general image and video generation API that overlaps with NiftyImages on dynamic image rendering.
- **SendGrid Mail API** — SendGrid sends the email that NiftyImages images are embedded into.
- **Mailchimp Marketing API** — Mailchimp manages the audience and campaigns that consume NiftyImages personalised content.
- **Brevo API** — Brevo (formerly Sendinblue) is a transactional and marketing email platform that consumes NiftyImages image URLs.

## FAQ

### Why is there no official OpenAPI spec for NiftyImages API?

NiftyImages does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call NiftyImages API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the NiftyImages API use?

NiftyImages supports an ApiKey passed in the ApiKey header, the same key in a query parameter, or HTTP Basic auth using the account credentials. Through Jentic, the ApiKey value is stored encrypted in the vault and attached to each request server-side.

### Can I update the target date on a countdown timer?

Yes. PUT `/v1/Timers/{timerKey}` accepts a new target date and updates the timer in place, so the same timer asset can be reused across campaigns by rolling the date forward.

### What are the rate limits for the NiftyImages API?

NiftyImages applies usage limits per account plan but does not publish numeric limits in the OpenAPI spec. Heavy data store sync jobs should batch writes and back off on HTTP 429 responses.

### How do I add a personalisation data store record through Jentic?

Run pip install jentic, search Jentic for 'add a record to a data store', and load POST `/v1/DataStores/{storeKey}/records.` Provide the storeKey and a fields object matching the schema returned by GET `/v1/DataStores/{storeKey}/fields.`

### Is the NiftyImages API free?

API access is bundled with paid NiftyImages plans. There is a free trial tier; commercial usage requires a paid subscription, the price of which depends on monthly image opens.

### Can I limit what my agent is allowed to do with the NiftyImages API?

Yes. Because you run Jentic One yourself, your own rules decide which NiftyImages operations and credentials the agent may use. Since NiftyImages puts the store key in the URL path, such as `/v1/DataStores/{storeKey}/records`, you can pin the agent to a single data store so it only adds and reads records there and nothing else. You also choose the exact operations it may call, so destructive ones like DELETE `/v1/DataStores/{storeKey}/records/{recordId}` or PUT `/v1/BeePlugin/users/{userId}/suspend` stay off unless you grant them.