For the complete documentation index, see llms.txt. This page is also available as Markdown.

Post Labels

Add labels to posts to organize content within a workspace. Labels can be used to filter posts, group content in analytics, and control labeled auto-scheduling timeslots.

For an overview of the different ways to publish and schedule posts, see Publishing Methods.

Overview

A label is a workspace scoped tag with a name and color. You can attach multiple labels to a post.

Labels are created automatically when you use a new label name while creating a post.

When Publer receives a label:

  1. It looks for an existing label with the same name in the workspace.

  2. If the label exists, it is reused.

  3. If it doesn't exist, a new label is created.

  4. The label is attached to the post.

Labels are supported when:

  • Scheduling a post

  • Publishing immediately

  • Creating drafts or ideas

  • Creating recycling posts

  • Creating recurring posts

  • Using bulk scheduling

Where Labels Go

There are two places where labels can be provided, but they serve different purposes:

Location
Format
Purpose

posts[].labels

Array of objects

Recommended for labeling posts

posts[].accounts[].labels

Array of strings

Used primarily for labeled auto-scheduling

Use posts[].labels for normal post labeling.

Account-level labels should only be used when you need to select labeled auto-scheduling timeslots.

Post-Level Labels

The recommended way to add labels is to include a labels array directly on the post.

Label Object

Field
Type
Required
Description

name

string

Yes

Label name

color

string

No

Hex color used when creating a new label

Label Matching

Labels are matched by name, case-insensitively.

For example:

all refer to the same label.

Whitespace is significant, however. These are different labels:

Trim label names before sending them.

If a label already exists, the color you provide is ignored and the existing color is preserved.

Requirements

posts[].labels must be an array of objects:

A plain array of strings is not supported at the post level:


Account-Level Labels

Account-level labels are provided inside accounts[]:

Use this format primarily when you want to control auto-scheduling through labeled timeslots.

When an account-level label is used:

  1. The label is attached to the post.

  2. If the label doesn't exist, it is created with the fixed color #434343.

  3. If no scheduled_at is provided, Publer uses the label to select posting-schedule timeslots.

Timeslot Selection

This applies when scheduled_at is not explicitly provided, including auto-scheduling, share_next, and recycling.

Labels
Timeslots used

Omitted or []

Unlabeled timeslots only

One label

Timeslots with exactly that label

Multiple labels

Timeslots matching any of the provided labels

If one label is provided and no matching timeslot exists, the post fails. There is no fallback to unlabeled timeslots.

If multiple labels are provided and none match, Publer falls back to unlabeled timeslots.

Timeslot labels are not available through the API. You can check them in the Publer web app under Accounts → Posting Schedule.

Account-Level Label Differences

  • Color is always #434343.

  • Recurring occurrences are not labeled; only the parent post is.

  • For recycling posts, the first label is also stored as the recycling label and returned in recycling_props.label.

  • If scheduled_at is explicitly provided, labels do not affect timeslot selection.

For normal post categorization, use post-level labels instead.


Label Colors

Publer supports the following colors in the web app:

Name
Hex

Green

#84FFBF

DarkBlue

#87C7F6

DarkRed

#F28EBB

Orange

#FCB000

Primary

#C0C2D1

Pink

#FF8787

DarkGreen

#73DDD8

LightOrange

#FDDF79

Blue

#C5B7FF

LightBlue

#B6DCF9

#C0C2D1 is the standard default color.

Colors are only applied when a label is created. Sending a different color for an existing label does not change its color.


Scheduling Posts with Labels

Labels work with the standard scheduling endpoint.

Example


Reading Labels

GET /api/v1/posts returns a labels array for each post. See Posts.


Updating Labels

Use:

The labels property uses the same format as post creation.

For recurring posts, updating labels applies the replacement to the parent post and its occurrences.

Removing a label from its last post does not delete the label from the workspace.


Limitations

  • Labels cannot be created independently; they are created when attached to a post.

  • Labels are scoped to a workspace.

  • Updating labels requires appropriate access to the post.


Best Practices

  • Use post-level labels by default. Use posts[].labels for normal post organization and categorization.

  • Use account-level labels for auto-scheduling. Only use accounts[].labels when you need labeled posting-schedule timeslots.

  • Keep names consistent. Trim whitespace and use consistent casing.

  • Send the complete label set when updating. PUT /api/v1/posts/{id} replaces the existing labels.

  • Use supported colors for consistent rendering in the Publer web app.


  • Publishing Methods — Learn about the different ways to publish and schedule posts

  • Recurring Posts — Label recurring posts and their generated occurrences

  • Media Handling — Upload media before attaching it to a post

  • Content Types — Supported post types and network-specific fields

Last updated

Was this helpful?