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.

{
  "bulk": {
    "state": "scheduled",
    "posts": [
      {
        "networks": {
          "facebook": {
            "type": "status",
            "text": "Check out our latest product!"
          }
        },
        "accounts": [
          {
            "id": "66db83154e299efa19a2d8eb",
            "scheduled_at": "2025-05-15T14:30:00Z"
          }
        ],
        "labels": [
          {
            "name": "Product Launch",
            "color": "#84FFBF"
          },
          {
            "name": "Q2 Campaign",
            "color": "#87C7F6"
          }
        ]
      }
    ]
  }
}

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:

Recipes
recipes
RECIPES

all refer to the same label.

Whitespace is significant, however. These are different labels:

Recipes
 Recipes
Recipes 

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:

"labels": [
  {
    "name": "Product Launch",
    "color": "#84FFBF"
  }
]

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

"labels": ["Product Launch"]

---

Account-Level Labels

Account-level labels are provided inside accounts[]:

{
  "bulk": {
    "state": "scheduled",
    "posts": [
      {
        "networks": {
          "facebook": {
            "type": "status",
            "text": "Evergreen tip of the week"
          }
        },
        "accounts": [
          {
            "id": "66db83154e299efa19a2d8eb",
            "labels": ["Recipes"]
          }
        ]
      }
    ]
  }
}

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 label matching is case-sensitive and exact.

For example, a timeslot labeled Recipes does not match recipes.

Post-level labels use case-insensitive matching, so these two behaviors are different.

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

{
  "bulk": {
    "state": "scheduled",
    "posts": [
      {
        "networks": {
          "facebook": {
            "type": "status",
            "text": "Check out our latest product!"
          }
        },
        "accounts": [
          {
            "id": "66db83154e299efa19a2d8eb",
            "scheduled_at": "2025-05-15T14:30:00Z"
          }
        ],
        "labels": [
          {
            "name": "Product Launch",
            "color": "#84FFBF"
          }
        ]
      }
    ]
  }
}

---

Reading Labels

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

{
  "posts": [
    {
      "id": "68176f0e8bee9dc9b0ce3427",
      "state": "scheduled",
      "type": "status",
      "text": "Check out our latest product!",
      "account_id": "66db83154e299efa19a2d8eb",
      "scheduled_at": "2025-05-15T14:30:00.000+02:00",
      "labels": [
        {
          "id": "6937e35e9823a2eeecfa378f",
          "name": "Product Launch",
          "color": "#84FFBF"
        },
        {
          "id": "69f327eb912f8d1e7e0bc7f0",
          "name": "Q2 Campaign",
          "color": "#87C7F6"
        }
      ]
    }
  ],
  "total": 1
}

---

Updating Labels

Use:

PUT /api/v1/posts/{id}

The labels property uses the same format as post creation.

{
  "post": {
    "text": "Updated copy",
    "labels": [
      {
        "name": "Product Launch",
        "color": "#84FFBF"
      }
    ]
  }
}

labels is a full replacement set, not an addition.

If you only want to add a label, first read the current labels and send the complete desired set.

If you omit labels entirely, all labels are removed from the post.

If the post currently has Product Launch and Q2 Campaign, sending only Product Launch removes Q2 Campaign.

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.

---

Related Topics

• 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