Skip to main content

Overview

Labels in Jasni allow you to categorize and organize emails. Unlike folders, an email can have multiple labels, making it easy to classify emails by topic, priority, or any custom criteria. Labels are particularly useful for AI agents that need to classify and route incoming emails.

Label Structure

A label object contains:
FieldTypeDescription
iduuidUnique identifier
namestringLabel name (1-50 characters)
colorstringHex color code (e.g., #6366f1)
descriptionstringOptional description
created_atdatetimeCreation timestamp
email_countintegerNumber of emails (when requested)

Creating Labels

Create a new label with a name and optional color:
POST /api/v1/labels
{
  "name": "Important",
  "color": "#ef4444",
  "description": "High priority emails"
}
If no color is provided, a random color from a predefined palette will be assigned.

Color Format

Colors must be in hex format: #RRGGBB
{
  "name": "Urgent",
  "color": "#dc2626"
}

Listing Labels

Retrieve all labels for your account:
GET /api/v1/labels
To include email counts:
GET /api/v1/labels?include_count=true

Response

{
  "success": true,
  "data": {
    "labels": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Important",
        "color": "#ef4444",
        "description": "High priority emails",
        "created_at": "2024-01-15T10:30:00Z",
        "email_count": 42
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "Follow Up",
        "color": "#f59e0b",
        "description": null,
        "created_at": "2024-01-15T10:35:00Z",
        "email_count": 15
      }
    ],
    "total": 2
  }
}

Use Cases

AI Email Classification

Use labels to let your AI agent classify incoming emails:
// Example: AI agent classifies incoming email
async function classifyEmail(email) {
  const classification = await aiModel.classify(email.text);
  
  // Apply appropriate label based on classification
  const labelMap = {
    'support': 'Support Request',
    'sales': 'Sales Inquiry',
    'urgent': 'Urgent',
    'spam': 'Likely Spam'
  };
  
  const labelName = labelMap[classification];
  // Apply label to email via API
}

Priority Management

Create a priority system with labels:
const priorityLabels = [
  { name: 'P1 - Critical', color: '#dc2626' },
  { name: 'P2 - High', color: '#f97316' },
  { name: 'P3 - Medium', color: '#eab308' },
  { name: 'P4 - Low', color: '#22c55e' }
];

Department Routing

Route emails to different teams:
const departmentLabels = [
  { name: 'Sales', color: '#3b82f6' },
  { name: 'Support', color: '#8b5cf6' },
  { name: 'Engineering', color: '#06b6d4' },
  { name: 'Marketing', color: '#ec4899' }
];

Suggested Label Colors

Here’s a palette of colors that work well together:
ColorHexUse Case
🔴 Red#ef4444Urgent, Important
🟠 Orange#f97316High Priority
🟡 Yellow#eab308Needs Attention
🟢 Green#22c55eResolved, Done
🔵 Blue#3b82f6Information
🟣 Purple#8b5cf6Personal
🩷 Pink#ec4899Marketing
🩵 Cyan#06b6d4Technical

Best Practices

Choose clear, descriptive label names that are easy to understand at a glance.
Too many labels can be overwhelming. Aim for 10-20 well-organized labels.
Establish a color scheme (e.g., red for urgent, green for resolved) and stick to it.
Use webhooks to automatically apply labels when emails arrive based on rules or AI classification.