IMAP Client Connector Guide

The IMAP Client connector lets you retrieve mailbox data from IMAP servers so your workflows can process inbound email content automatically. It is useful for inbox triage, ticket intake, notification processing, and unread-message monitoring.

Configure IMAP access

Set imap_host, username, and password to the mailbox credentials you want Tealfabric to read. For most providers, keep use_ssl enabled with imap_port set to 993 so credentials and message data are encrypted in transit.

Use mailbox to target a specific folder such as INBOX or Support, and tune timeout for larger mailbox operations. Run test before enabling production automations so you can validate connectivity and permissions early.

Retrieve messages with receive

Use receive when you need mailbox polling with custom search_criteria, pagination, or optional body retrieval. This operation gives you the most control when building workflow logic around sender filters, date windows, or keyword matching.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

async function receiveUnreadInvoices(integrationId: string) {
  const response = await fetch(`${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`, {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "X-Tenant-ID": tenantId,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      operation: "receive",
      search_criteria: 'UNSEEN AND SUBJECT "invoice"',
      limit: 25,
      offset: 0,
      include_body: false
    }),
  });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  return response.json();
}

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "receive",
    "search_criteria": "UNSEEN AND SUBJECT \"invoice\"",
    "limit": 25,
    "offset": 0,
    "include_body": false
  }'

{
  "success": true,
  "data": {
    "message_count": 3,
    "total_available": 8,
    "emails": [
      {
        "message_number": 42,
        "uid": 8021,
        "subject": "Invoice INV-1042",
        "from": "billing@example.com",
        "to": "ops@example.com",
        "date": "2026-05-08 08:11:00",
        "seen": false
      }
    ]
  }
}

Poll unread mail with sync

Use sync when you want a simpler unread-mail workflow without manually setting search_criteria. This operation behaves like receive with UNSEEN preconfigured and is often the fastest way to build intake pipelines.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

async function syncUnreadMessages(integrationId: string) {
  const response = await fetch(`${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`, {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "X-Tenant-ID": tenantId,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      operation: "sync",
      limit: 10,
      offset: 0,
      include_body: true
    }),
  });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  return response.json();
}

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "sync",
    "limit": 10,
    "offset": 0,
    "include_body": true
  }'

{
  "success": true,
  "data": {
    "message_count": 2,
    "total_available": 2,
    "emails": [
      {
        "message_number": 44,
        "uid": 8044,
        "subject": "Action required: contract review",
        "from": "legal@example.com",
        "to": "team@example.com",
        "date": "2026-05-08 09:30:00",
        "seen": false,
        "body": "Please review the attached draft..."
      }
    ]
  }
}

Validate connectivity with test

Run test before production polling to confirm host, port, TLS, credentials, and mailbox access. The connector returns mailbox status metrics under data.details.

{
  "success": true,
  "data": {
    "message": "IMAP connection test successful",
    "details": {
      "imap_host": "imap.example.com",
      "imap_port": 993,
      "use_ssl": true,
      "mailbox": "INBOX",
      "total_messages": 120,
      "recent_messages": 0,
      "unseen_messages": 4,
      "mailbox_count": 6
    }
  }
}

IMAP search criteria examples

search_criteria accepts IMAP-style terms that the connector maps to ImapFlow search queries. Supported patterns include ALL, UNSEEN, SEEN, FLAGGED, header filters such as FROM "sender@example.com" and SUBJECT "keyword", date filters such as SINCE "01-May-2026", and AND combinations like UNSEEN AND SUBJECT "invoice".

receive defaults search_criteria to ALL when omitted (legacy ?? semantics). sync defaults to UNSEEN only when search_criteria is omitted. Complex OR/NOT expressions are not translated yet; use simpler AND combinations for parity with legacy imap_search behavior.

When include_body is true, body contains the RFC822 message source (ImapFlow source), which may differ from legacy connector text extraction.

Troubleshooting and operational guidance

Authentication failures usually come from incorrect credentials or account security requirements such as app passwords. Connection failures are commonly tied to host, port, TLS mismatch, or blocked network access between your runtime and the IMAP server.

If mailbox reads are slower than expected, reduce include_body, page through results with limit and offset, and run test before every large sync schedule. This keeps email ingestion predictable and easier to debug in production.

Additional resources

• IMAP Protocol RFC 9051
• IMAP client library documentation
• Gmail IMAP settings