Skip to main content
The SDK provides two ways to work with labels:
  • jasni.labels - Manage labels themselves (create, list)
  • jasni.emails.labels - Manage labels on specific emails (assign, remove, list)

List Labels

Retrieve all labels:
const { labels, total } = await jasni.labels.list({
  includeCount: true,  // Optional: include email count per label
})

labels.forEach(label => {
  console.log(`${label.name}: ${label.email_count || 0} emails`)
})

Options

ParameterTypeRequiredDescription
includeCountbooleanNoInclude email count per label. Default: false

Response

interface Label {
  id: string
  name: string
  color: string
  description?: string
  created_at: string
  email_count?: number
}

interface ListLabelsResponse {
  labels: Label[]
  total: number
}

Create Label

Create a new label:
const { label } = await jasni.labels.create({
  name: 'Important',
  color: '#ff0000',               // Optional: hex color
  description: 'Important emails', // Optional
})

console.log('Created label:', label.id)

Options

ParameterTypeRequiredDescription
namestringYesLabel name
colorstringNoHex color (e.g., #ff0000). Auto-generated if not provided.
descriptionstringNoDescription

Response

interface CreateLabelResponse {
  label: Label
  message: string
}

Get Email Labels

Get labels assigned to a specific email:
const { labels, message_id, account } = await jasni.emails.labels.list(123, {
  account: '[email protected]',
  folder: 'INBOX',  // Optional
})

labels.forEach(label => {
  console.log(`- ${label.name} (applied by: ${label.applied_by})`)
})

Options

ParameterTypeRequiredDescription
accountstringYesEmail account
folderstringNoFolder. Default: INBOX

Response

interface EmailLabel extends Label {
  applied_by: string
  applied_at: string
  metadata?: Record<string, unknown>
}

interface GetEmailLabelsResponse {
  labels: EmailLabel[]
  message_id: string
  account: string
}

Assign Labels to Email

Assign labels to an email:
// Using label names (creates if they don't exist)
const result = await jasni.emails.labels.assign(123, {
  account: '[email protected]',
  labels: ['Important', 'Work'],
  agentName: 'my-agent',  // Optional: for tracking
  metadata: { reason: 'Auto-categorized' },  // Optional
})

// Or using existing label IDs
const result = await jasni.emails.labels.assign(123, {
  account: '[email protected]',
  labelIds: ['label-id-1', 'label-id-2'],
})

console.log('Labels assigned:', result.labels.map(l => l.name))
console.log('Created labels:', result.created_labels)

Options

ParameterTypeRequiredDescription
accountstringYesEmail account
folderstringNoFolder. Default: INBOX
labelIdsstring[]NoArray of existing label IDs to assign
labelsstring[]NoArray of label names (creates if not exists)
agentNamestringNoName of the agent applying labels
metadataobjectNoAdditional context about the categorization
You must provide either labelIds or labels (or both). Using labels with names will automatically create any labels that don’t exist.

Response

interface AssignLabelsResponse {
  labels: EmailLabel[]
  created_labels: Pick<Label, 'id' | 'name' | 'color'>[]
  message_id: string
  account: string
  message: string
}

Remove Labels from Email

Remove labels from an email:
const result = await jasni.emails.labels.remove(123, {
  account: '[email protected]',
  labelIds: ['label-id-1', 'label-id-2'],
})

console.log(`Removed ${result.removed_count} labels`)

Options

ParameterTypeRequiredDescription
accountstringYesEmail account
folderstringNoFolder. Default: INBOX
labelIdsstring[]YesLabel IDs to remove

Response

interface RemoveLabelsResponse {
  removed_count: number
  message_id: string
  message: string
}

Example: Label Workflow

Here’s a complete example of working with labels:
import { Jasni } from 'jasni-sdk'

const jasni = new Jasni('jsk_your_api_key')

async function labelWorkflow() {
  const account = '[email protected]'
  
  // Create some labels
  const { label: importantLabel } = await jasni.labels.create({
    name: 'Important',
    color: '#ff0000',
    description: 'High priority emails',
  })
  
  const { label: workLabel } = await jasni.labels.create({
    name: 'Work',
    color: '#0066cc',
    description: 'Work-related emails',
  })
  
  console.log('Created labels:', importantLabel.name, workLabel.name)
  
  // List all labels with counts
  const { labels } = await jasni.labels.list({ includeCount: true })
  console.log('All labels:', labels.map(l => `${l.name} (${l.email_count})`))
  
  // Get recent emails
  const { emails } = await jasni.emails.list({ account, limit: 10 })
  
  // Apply labels to emails based on criteria
  for (const email of emails) {
    const labelsToAssign: string[] = []
    
    // Example: auto-categorize based on subject
    if (email.subject.toLowerCase().includes('urgent')) {
      labelsToAssign.push('Important')
    }
    
    if (email.from.toString().includes('company.com')) {
      labelsToAssign.push('Work')
    }
    
    if (labelsToAssign.length > 0) {
      await jasni.emails.labels.assign(email.uid, {
        account,
        labels: labelsToAssign,
        agentName: 'auto-categorizer',
        metadata: { 
          rule: 'subject-keyword-match',
          timestamp: new Date().toISOString(),
        },
      })
      
      console.log(`Labeled email "${email.subject}" with:`, labelsToAssign)
    }
  }
  
  // Get labels for a specific email
  if (emails.length > 0) {
    const { labels: emailLabels } = await jasni.emails.labels.list(emails[0].uid, { account })
    console.log('Labels on first email:', emailLabels.map(l => l.name))
  }
}

labelWorkflow().catch(console.error)

AI-Powered Email Categorization

Labels are particularly useful for AI-powered email categorization. Here’s an example:
import { Jasni } from 'jasni-sdk'

const jasni = new Jasni('jsk_your_api_key')

async function categorizeEmail(emailUid: number, account: string) {
  // Get the email content
  const { email } = await jasni.emails.get(emailUid, { account })
  
  // Use your AI to categorize (example with hypothetical AI service)
  const categories = await analyzeEmailWithAI(email.subject, email.text)
  
  // Apply the categories as labels
  if (categories.length > 0) {
    await jasni.emails.labels.assign(emailUid, {
      account,
      labels: categories,
      agentName: 'ai-categorizer',
      metadata: {
        model: 'gpt-4',
        confidence: 0.95,
        analyzed_at: new Date().toISOString(),
      },
    })
  }
}