Skip to main content
The Inbox API manages incoming documents and email attachments, with AI-powered matching to transactions and invoices.

​
Query Endpoints

​
get

Retrieve a paginated list of inbox items.
​
q
string
Search query for filename or content
​
status
string
Filter by status: “processing” | “pending” | “matched” | “archived”
​
sort
array
Array of sort objects
​
limit
number
Number of results per page
import { trpc } from '@/lib/trpc';

const { data, meta } = await trpc.inbox.get.query({
  status: 'pending',
  limit: 20,
});

​
getById

Retrieve a specific inbox item by ID.
​
id
string
required
Inbox item UUID
​
item
object
const item = await trpc.inbox.getById.query({
  id: 'inbox-uuid',
});

​
getByStatus

Get inbox items filtered by status.
​
status
string
required
Status to filter by
​
items
array
Array of inbox item objects
const pending = await trpc.inbox.getByStatus.query({
  status: 'pending',
});
Search inbox items (for transaction matching).
​
q
string
required
Search query
​
transactionId
string
Transaction UUID to match against
​
limit
number
Maximum number of results (default: 10)
​
results
array
Array of matching inbox items
const results = await trpc.inbox.search.query({
  q: 'amazon receipt',
  limit: 5,
});

​
checkAttachments

Check if an inbox item is attached to transactions/invoices.
​
id
string
required
Inbox item UUID
​
data
object

​
Mutation Endpoints

​
create

Create a new inbox item (after file upload).
​
filename
string
required
Original filename
​
filePath
array
required
Storage path tokens
​
mimetype
string
required
MIME type
​
size
number
required
File size in bytes
​
item
object
Created inbox item
const item = await trpc.inbox.create.mutate({
  filename: 'receipt.pdf',
  filePath: ['inbox', 'team-id', 'receipt.pdf'],
  mimetype: 'application/pdf',
  size: 102400,
});

​
processAttachments

Trigger processing for uploaded attachments.
​
attachments
array
required
Array of attachment objects to process
type Attachment = {
  filePath: string[];      // Storage path
  mimetype: string;        // MIME type
  size: number;            // File size
  referenceId?: string;    // Email reference ID
  website?: string;        // Extracted website
  senderEmail?: string;    // Sender email
  inboxAccountId?: string; // Inbox account UUID
};
​
data
object
const result = await trpc.inbox.processAttachments.mutate([
  {
    filePath: ['inbox', 'team-id', 'receipt.pdf'],
    mimetype: 'application/pdf',
    size: 102400,
    senderEmail: '[email protected]',
    inboxAccountId: 'account-uuid',
  },
]);

console.log('Processing jobs:', result.jobs);

​
update

Update an inbox item.
​
id
string
required
Inbox item UUID
​
displayName
string
New display name
​
status
string
New status
await trpc.inbox.update.mutate({
  id: 'inbox-uuid',
  displayName: 'Amazon Receipt - Nov 2024',
  status: 'archived',
});

​
delete

Delete an inbox item and its file.
​
id
string
required
Inbox item UUID
await trpc.inbox.delete.mutate({
  id: 'inbox-uuid',
});

​
deleteMany

Delete multiple inbox items at once.
​
ids
array
required
Array of inbox item UUIDs
await trpc.inbox.deleteMany.mutate({
  ids: ['uuid1', 'uuid2', 'uuid3'],
});

​
Transaction Matching

​
matchTransaction

Manually match an inbox item to a transaction.
​
id
string
required
Inbox item UUID
​
transactionId
string
required
Transaction UUID to match
​
data
object
Updated inbox item with transaction link
await trpc.inbox.matchTransaction.mutate({
  id: 'inbox-uuid',
  transactionId: 'transaction-uuid',
});

​
unmatchTransaction

Remove transaction match from an inbox item.
​
id
string
required
Inbox item UUID
await trpc.inbox.unmatchTransaction.mutate({
  id: 'inbox-uuid',
});

​
confirmMatch

Confirm an AI-suggested transaction match.
​
suggestionId
string
required
Suggestion UUID
​
inboxId
string
required
Inbox item UUID
​
transactionId
string
required
Transaction UUID
await trpc.inbox.confirmMatch.mutate({
  suggestionId: 'suggestion-uuid',
  inboxId: 'inbox-uuid',
  transactionId: 'transaction-uuid',
});

​
declineMatch

Decline an AI-suggested transaction match.
​
suggestionId
string
required
Suggestion UUID
​
inboxId
string
required
Inbox item UUID
await trpc.inbox.declineMatch.mutate({
  suggestionId: 'suggestion-uuid',
  inboxId: 'inbox-uuid',
});

​
retryMatching

Retry AI matching for an inbox item.
​
id
string
required
Inbox item UUID
​
data
object
const { jobId } = await trpc.inbox.retryMatching.mutate({
  id: 'inbox-uuid',
});

​
Blocklist Management

​
blocklist.get

Get the inbox blocklist (filtered senders/domains).
​
items
array
Array of blocklist entry objects
const blocklist = await trpc.inbox.blocklist.get.query({});

​
blocklist.create

Add an entry to the blocklist.
​
type
string
required
“email” | “domain”
​
value
string
required
Email address or domain to block
// Block specific email
await trpc.inbox.blocklist.create.mutate({
  type: 'email',
  value: '[email protected]',
});

// Block entire domain
await trpc.inbox.blocklist.create.mutate({
  type: 'domain',
  value: 'marketing.com',
});

​
blocklist.delete

Remove an entry from the blocklist.
​
id
string
required
Blocklist entry UUID
await trpc.inbox.blocklist.delete.mutate({
  id: 'blocklist-uuid',
});

​
Email Integration

The inbox automatically processes attachments from connected email accounts.

​
Setting Up Email Integration

  1. Connect an email account via the inboxAccounts tRPC router
  2. Email attachments are automatically synced
  3. AI extracts vendor info and suggests transaction matches
  4. Confirm or decline matches in the UI

​
Automatic Processing

When an email attachment is received:
  1. Extract - OCR and text extraction
  2. Analyze - AI identifies vendor, amount, date
  3. Match - Vector search finds similar transactions
  4. Suggest - Top matches presented for confirmation
// Get inbox items with suggestions
const { data } = await trpc.inbox.get.query({ status: 'pending' });

data.forEach(item => {
  if (item.suggestedMatches?.length > 0) {
    console.log(`${item.displayName} has ${item.suggestedMatches.length} suggested matches`);
  }
});

Build docs developers (and LLMs) love

Get started for freeTalk to us