Transactional

Inboxes

Managing support inboxes

Inboxes

Inboxes help you organize support conversations by team, product, or any other criteria.

Overview

An inbox is a container for conversations. Each organization can have multiple inboxes:

  • Website Support - General website inquiries
  • Sales - Pre-sales questions
  • Technical Support - Technical issues
  • Billing - Payment and billing questions

Creating an Inbox

Via Dashboard

  1. Navigate to Support > Inboxes
  2. Click Create Inbox
  3. Fill in the details:
    • Name: Display name for the inbox
    • Description: Optional description
    • Email: Optional email address for email routing
  4. Click Create

Via API

const response = await fetch('/api/support/inboxes', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your-api-key',
  },
  body: JSON.stringify({
    name: 'Technical Support',
    description: 'Technical issues and questions',
    email: 'support@example.com',
  }),
});

Inbox Settings

General Settings

{
  name: 'Technical Support',
  description: 'Technical issues and questions',
  email: 'support@example.com',
  isDefault: false,
  color: '#3B82F6',
  icon: 'wrench'
}

Assignment Rules

Configure automatic assignment:

{
  assignmentRules: {
    type: 'round_robin', // 'round_robin' | 'least_busy' | 'manual'
    fallbackUserId: 'user-123',
    workingHours: {
      enabled: true,
      timezone: 'America/New_York',
      schedule: {
        monday: { start: '09:00', end: '17:00' },
        tuesday: { start: '09:00', end: '17:00' },
        // ...
      }
    }
  }
}

Auto-Responders

Set up automatic responses:

{
  autoResponder: {
    enabled: true,
    message: "Thanks for reaching out! We typically respond within 2 hours.",
    delaySeconds: 5,
    conditions: {
      outsideWorkingHours: true
    }
  }
}

Routing Conversations

By URL

Route conversations based on the page they're started from:

{
  routingRules: [
    {
      condition: { url: { contains: '/pricing' } },
      inboxId: 'sales-inbox-id'
    },
    {
      condition: { url: { contains: '/docs' } },
      inboxId: 'technical-inbox-id'
    }
  ]
}

By User Attribute

Route based on user data:

{
  routingRules: [
    {
      condition: { userAttribute: { key: 'plan', value: 'enterprise' } },
      inboxId: 'priority-inbox-id'
    },
    {
      condition: { userAttribute: { key: 'language', value: 'es' } },
      inboxId: 'spanish-inbox-id'
    }
  ]
}

By Initial Message

Route based on keywords:

{
  routingRules: [
    {
      condition: { message: { contains: ['billing', 'payment', 'invoice'] } },
      inboxId: 'billing-inbox-id'
    }
  ]
}

Team Management

Adding Team Members

const response = await fetch('/api/support/inboxes/{inboxId}/members', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your-api-key',
  },
  body: JSON.stringify({
    userId: 'user-123',
    role: 'agent' // 'agent' | 'admin'
  }),
});

Member Roles

RolePermissions
AdminFull access, manage settings and members
AgentHandle conversations, view reports

Availability Status

Team members can set their availability:

// Set agent as available
await fetch('/api/support/inboxes/{inboxId}/members/{userId}/availability', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your-api-key',
  },
  body: JSON.stringify({
    status: 'available' // 'available' | 'away' | 'offline'
  }),
});

Working Hours

Configure when the inbox is "open":

const response = await fetch('/api/support/inboxes/{inboxId}', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your-api-key',
  },
  body: JSON.stringify({
    workingHours: {
      enabled: true,
      timezone: 'America/New_York',
      schedule: {
        monday: { start: '09:00', end: '17:00' },
        tuesday: { start: '09:00', end: '17:00' },
        wednesday: { start: '09:00', end: '17:00' },
        thursday: { start: '09:00', end: '17:00' },
        friday: { start: '09:00', end: '17:00' },
        saturday: null, // Closed
        sunday: null    // Closed
      },
      holidays: [
        '2024-12-25',
        '2024-01-01'
      ]
    }
  }),
});

Outside Hours Message

{
  outsideHoursMessage: "We're currently offline. We'll respond when we're back online tomorrow at 9 AM EST."
}

Inbox Analytics

Get Inbox Stats

const response = await fetch('/api/support/inboxes/{inboxId}/stats', {
  headers: {
    'X-API-Key': 'your-api-key',
  },
});
 
const { data } = await response.json();

Response:

{
  data: {
    openConversations: 15,
    unassignedConversations: 3,
    avgResponseTime: 120, // seconds
    avgResolutionTime: 3600, // seconds
    conversationsToday: 25,
    resolvedToday: 20,
    csat: 4.5 // out of 5
  }
}

Team Performance

const response = await fetch('/api/support/inboxes/{inboxId}/stats/team', {
  headers: {
    'X-API-Key': 'your-api-key',
  },
});
 
const { data } = await response.json();

Response:

{
  data: {
    members: [
      {
        userId: 'user-123',
        name: 'John Doe',
        conversationsHandled: 50,
        avgResponseTime: 90,
        csat: 4.8
      }
    ]
  }
}

Email Integration

Forwarding Email to Inbox

Set up email forwarding to create conversations from email:

  1. Go to Inbox Settings > Email
  2. Copy the forwarding address: inbox-abc@mail.usetransactional.com
  3. Configure your email provider to forward to this address

Reply by Email

Enable agents to reply via email:

{
  emailSettings: {
    replyByEmail: true,
    fromAddress: 'support@example.com',
    fromName: 'Support Team'
  }
}

API Reference

List Inboxes

GET /api/support/inboxes

Get Inbox

GET /api/support/inboxes/:inboxId

Create Inbox

POST /api/support/inboxes

Update Inbox

PUT /api/support/inboxes/:inboxId

Delete Inbox

DELETE /api/support/inboxes/:inboxId

List Inbox Members

GET /api/support/inboxes/:inboxId/members

Add Inbox Member

POST /api/support/inboxes/:inboxId/members

Remove Inbox Member

DELETE /api/support/inboxes/:inboxId/members/:userId

Next Steps