Emails API

The client.emails API provides methods for managing received emails, including listing, reading, organizing, and deleting.

Methods Overview

Method	Description
`list(options?)`	List emails with filtering and pagination
`get(emailId)`	Get a single email
`update(emailId, options)`	Update email (folder, read status)
`delete(emailId, options?)`	Delete an email
`markAsRead(emailId)`	Mark email as read
`markAsUnread(emailId)`	Mark email as unread
`move(emailId, folder)`	Move email to folder
`archive(emailId)`	Archive an email
`count(folder?)`	Count emails in a folder

All methods require authentication.

list()

Returns a paginated list of emails.

const result = await client.emails.list(options?: ListEmailsOptions): Promise<PaginatedResponse<Email>>

Parameters

Field	Type	Default	Description
`folder`	string	-	Filter by folder (inbox, archive, trash, or custom)
`limit`	number	50	Max emails to return (1-100)
`offset`	number	0	Number of emails to skip

Returns

interface PaginatedResponse<Email> {
  data: Email[];
  total: number;
  limit: number;
  offset: number;
}

interface Email {
  id: string;
  from: { address: string; name?: string };
  to: string[];
  subject: string;
  bodyText: string | null;
  bodyHtml: string | null;
  receivedAt: number;
  isRead: boolean;
  folder: string;
}

Example

// List inbox emails
const inbox = await client.emails.list({ folder: 'inbox' });

console.log(`You have ${inbox.total} emails`);

for (const email of inbox.data) {
  console.log(`From: ${email.from.name || email.from.address}`);
  console.log(`Subject: ${email.subject}`);
  console.log(`Read: ${email.isRead}`);
}

Pagination Example

async function getAllEmails(client: ClawMailClient) {
  const allEmails: Email[] = [];
  let offset = 0;
  const limit = 50;

  while (true) {
    const page = await client.emails.list({ limit, offset });
    allEmails.push(...page.data);

    if (page.data.length < limit) break;
    offset += limit;
  }

  return allEmails;
}

Folder Examples

// Inbox (default for new emails)
const inbox = await client.emails.list({ folder: 'inbox' });

// Archived emails
const archived = await client.emails.list({ folder: 'archive' });

// Trash
const trash = await client.emails.list({ folder: 'trash' });

// Custom folder
const important = await client.emails.list({ folder: 'important' });

get()

Retrieves a single email with full content.

const email = await client.emails.get(emailId: string): Promise<Email>

Parameters

Field	Type	Description
`emailId`	string	The email's unique identifier

Example

const email = await client.emails.get('ml_abc123');

console.log('From:', email.from.address);
console.log('Subject:', email.subject);
console.log('Received:', new Date(email.receivedAt));

// Display body content
if (email.bodyText) {
  console.log('Text:', email.bodyText);
}

if (email.bodyHtml) {
  console.log('HTML:', email.bodyHtml);
}

Errors

Error	When
`ClawMailValidationError`	Missing email ID
`ClawMailApiError` (404)	Email doesn't exist

update()

Updates an email's properties (folder, read status).

const email = await client.emails.update(
  emailId: string,
  options: UpdateEmailOptions
): Promise<Email>

Parameters

Field	Type	Description
`emailId`	string	The email's unique identifier
`options.folder`	string	Move to this folder
`options.isRead`	boolean	Mark as read (true) or unread (false)

At least one option must be provided.

Example

// Mark as read
await client.emails.update('ml_abc123', { isRead: true });

// Move to archive
await client.emails.update('ml_abc123', { folder: 'archive' });

// Move and mark read in one call
await client.emails.update('ml_abc123', {
  folder: 'archive',
  isRead: true
});

markAsRead()

Convenience method to mark an email as read.

const email = await client.emails.markAsRead(emailId: string): Promise<Email>

Equivalent to: client.emails.update(emailId, { isRead: true })

Example

await client.emails.markAsRead('ml_abc123');

markAsUnread()

Convenience method to mark an email as unread.

const email = await client.emails.markAsUnread(emailId: string): Promise<Email>

Equivalent to: client.emails.update(emailId, { isRead: false })

Example

await client.emails.markAsUnread('ml_abc123');

move()

Convenience method to move an email to a folder.

const email = await client.emails.move(
  emailId: string,
  folder: string
): Promise<Email>

Equivalent to: client.emails.update(emailId, { folder })

Example

// Move to archive
await client.emails.move('ml_abc123', 'archive');

// Move to custom folder
await client.emails.move('ml_abc123', 'important');

// Recover from trash
await client.emails.move('ml_abc123', 'inbox');

archive()

Convenience method to archive an email (moves to 'archive' folder and marks as read).

const email = await client.emails.archive(emailId: string): Promise<Email>

Equivalent to: client.emails.update(emailId, { folder: 'archive', isRead: true })

Example

// Process and archive emails
const inbox = await client.emails.list({ folder: 'inbox' });

for (const email of inbox.data) {
  // Process the email...
  await processEmail(email);

  // Archive it
  await client.emails.archive(email.id);
}

delete()

Deletes an email (moves to trash or permanently deletes).

const result = await client.emails.delete(
  emailId: string,
  options?: DeleteEmailOptions
): Promise<DeleteEmailResponse>

Parameters

Field	Type	Default	Description
`emailId`	string	-	The email's unique identifier
`options.permanent`	boolean	false	Permanently delete (cannot be undone)

Returns

interface DeleteEmailResponse {
  success: boolean;
  message: string;
}

Example

// Soft delete (move to trash)
await client.emails.delete('ml_abc123');
// { success: true, message: 'Email moved to trash' }

// Permanent delete
await client.emails.delete('ml_abc123', { permanent: true });
// { success: true, message: 'Email permanently deleted' }

Empty Trash

async function emptyTrash(client: ClawMailClient) {
  const trash = await client.emails.list({ folder: 'trash' });

  for (const email of trash.data) {
    await client.emails.delete(email.id, { permanent: true });
  }

  console.log(`Deleted ${trash.data.length} emails`);
}

Deleting an email that's already in trash automatically performs a permanent delete.

count()

Gets the count of emails in a folder.

const count = await client.emails.count(folder?: string): Promise<number>

Parameters

Field	Type	Default	Description
`folder`	string	-	Folder to count (omit for all folders)

Example

// Count inbox emails
const inboxCount = await client.emails.count('inbox');
console.log(`You have ${inboxCount} emails in inbox`);

// Count all emails
const totalCount = await client.emails.count();
console.log(`Total emails: ${totalCount}`);

// Check for unread (simple approach)
const inbox = await client.emails.list({ folder: 'inbox' });
const unread = inbox.data.filter(e => !e.isRead).length;

Complete Workflow Example

import { ClawMailClient } from '@clawmail/client';

async function processInbox(client: ClawMailClient) {
  // 1. List unread inbox emails
  const inbox = await client.emails.list({ folder: 'inbox' });

  console.log(`Processing ${inbox.total} emails...`);

  for (const email of inbox.data) {
    // 2. Get full email content
    const full = await client.emails.get(email.id);

    console.log(`From: ${full.from.address}`);
    console.log(`Subject: ${full.subject}`);

    // 3. Process based on content
    if (full.subject?.includes('URGENT')) {
      // Move urgent emails to a special folder
      await client.emails.move(email.id, 'urgent');
      console.log('Moved to urgent');
    } else if (full.from.address.endsWith('@spam.com')) {
      // Delete spam
      await client.emails.delete(email.id, { permanent: true });
      console.log('Deleted spam');
    } else {
      // Archive normal emails after processing
      await client.emails.archive(email.id);
      console.log('Archived');
    }
  }

  // 4. Report final counts
  const urgentCount = await client.emails.count('urgent');
  const archiveCount = await client.emails.count('archive');

  console.log(`Urgent: ${urgentCount}, Archived: ${archiveCount}`);
}

Emails API

On this page