Pinterest Auto-Posting

Pinterest still drives real traffic to long-form content — recipes, how-tos, roundups, visual guides. jekcms ships with a native Pinterest integration that, once configured, pins your post's featured image to a chosen board every time a post goes live, using the post title + excerpt + canonical URL. No n8n workflow required for the basic case; it runs inside jekcms's own queue.

This guide covers API setup, admin config, per-post overrides, and the pin template syntax.

What the integration does

When a post moves to Published status, jekcms:

Grabs the featured image (or, if none, the site's default OG image)
Builds a pin description from your template — defaults to {title}\n\n{excerpt}
Posts to Pinterest via the v5 API against your configured board
Appends the canonical post URL as the pin's destination link

Pins are queued — they fire asynchronously after publish, so a slow Pinterest API response never blocks your editor save.

Step 1 — Get a Pinterest API access token

Go to [developers.pinterest.com](https://developers.pinterest.com) and sign in with the Pinterest account that owns the board you want to pin to
My apps → Create app
Fill in app name, description, website URL (use your jekcms site URL)
Once the app is approved, open it and go to the Configure tab
Under Generate access token, request the scopes boards:read, pins:read, pins:write
Copy the generated access token — long string starting with pina_...

Pinterest access tokens are long-lived (60 days by default; can be refreshed) but not permanent. Set a calendar reminder to rotate before the expiry, or wire up the refresh-token flow (see Troubleshooting).

Step 2 — Find your board ID

In a browser, go to the board you want to pin to. The URL looks like https://www.pinterest.com/username/my-recipes/. The numeric board ID isn't in the URL — fetch it via the API:

curl -H "Authorization: Bearer pina_YOUR_TOKEN" \
  https://api.pinterest.com/v5/boards

The response lists every board with its id field (a 16-digit number). Copy the ID for the target board.

Step 3 — Configure jekcms

Admin → Settings → Integrations → Pinterest:

Access token — paste the pina_... string. Stored encrypted (AES-256, per-install fingerprint).
Target board ID — the 16-digit ID from step 2
Default hashtags — comma-separated, appended to every pin (e.g., recipe, cooking, dinner). Leave blank if you don't want hashtags.
Pin template — see below
Auto-pin on publish — master on/off

Click Test connection — jekcms posts a test pin with a placeholder image to verify the token + board ID work. You can delete the test pin from Pinterest afterward.

Per-post auto-pin toggle

In the post editor sidebar, the Pinterest panel shows a Pin on publish checkbox. It defaults to whatever you set in Settings, but you can override per-post:

Leave on for recipe/roundup posts
Turn off for internal updates, changelog entries, or anything without a meaningful featured image

If a post has no featured image and auto-pin is on, the job is skipped and logged as pinterest: skipped - no featured image.

Queue behavior and retries

Pinterest pins fire through jekcms's outbound queue, not synchronously. Flow:

Post transitions to Published → queue item created
Within 60 seconds, the cron worker (queue_worker) picks up the job
On success → logged, pin ID stored on the post row
On failure → retry with exponential backoff (1 min, 5 min, 30 min), max 3 attempts
After 3 failures → logged as permanent failure, admin notified

See queued jobs under Automation → Queue → Pinterest. You can manually retry a failed job from there.

Pin template customization

The default template is:

{title}

{excerpt}

Available placeholders:

{title} — post title
{excerpt} — post excerpt (truncated to 480 chars — Pinterest's limit is 500)
{category} — first category name
{tags} — comma-separated tag list
{author} — author display name
{site_name} — from Settings → General

Example template:

{title} | {category}

{excerpt}

More on {site_name}

Keep in mind Pinterest strips most HTML; plain text + line breaks only.

Troubleshooting

"Rate limit exceeded." Pinterest allows roughly 1,000 requests per hour per token. If you bulk-publish 50 posts at once, pins queue and throttle naturally — no action needed. Check Queue logs to see progress.

"Invalid access token" or 401 errors. Token expired (60-day default). Generate a fresh token in the Pinterest dashboard and paste it into Settings. For zero-downtime rotation, use Pinterest's refresh-token flow — see [developers.pinterest.com/docs/api/v5/#auth](https://developers.pinterest.com/docs/api/v5/).

"Image too small" / pin rejected. Pinterest requires images at least 600×900 px for best display. Smaller images may upload but look blurry. Under Settings → Performance, enable Auto-upscale featured images or upload larger source images.

Pins fire but don't appear on the board. Check the board ID — a wrong ID sometimes lands pins on a secondary board under the same account. Re-verify via the curl call in step 2.