POP3 Client Connector Guide

The POP3 client connector lets Tealfabric workflows connect to POP3 mailboxes and retrieve messages for downstream processing. It is useful for inbox ingestion workflows such as support queue intake, vendor email parsing, and document extraction pipelines.

Configure mailbox access

Set pop3_host, username, and password for the mailbox you want to read. Use pop3_port, use_ssl, and timeout to match your mail server requirements and network profile.

This connector uses standard POP3 credentials, not OAuth2. Before production rollout, validate account access and server settings with a test operation to prevent mailbox connection failures in scheduled workflows.

Test connectivity with test

Use test to verify host, port, credentials, and SSL/TLS settings before running retrieval jobs. This is the fastest way to confirm that the integration can authenticate successfully.

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

async function testPop3Connection(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: "test"
    }),
  });
  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": "test"
  }'

{
  "success": true,
  "details": {
    "host": "pop.mail.example.com",
    "port": 995,
    "ssl": true
  }
}

Retrieve messages with receive

Use receive to fetch messages from the POP3 mailbox for parsing or routing. POP3 does not provide rich server-side filters, so workflows usually fetch a batch and then filter by subject, sender, or date in downstream steps.

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

async function receiveMessages(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",
      query: {
        limit: 25
      }
    }),
  });
  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",
    "query": {
      "limit": 25
    }
  }'

{
  "success": true,
  "record_count": 2,
  "data": [
    {
      "message_id": "<ENTITY_ID>",
      "subject": "Invoice 2026-05-08",
      "from": "billing@example.com"
    },
    {
      "message_id": "<ENTITY_ID>",
      "subject": "Support request #4312",
      "from": "customer@example.org"
    }
  ]
}

Reliability guidance

POP3 retrieval issues usually come from incorrect host or port settings, SSL/TLS mismatch, or invalid mailbox credentials. Resolve connectivity and authentication first, then tune batch size and timeout for stable mailbox ingestion.

For predictable automation, process messages idempotently and keep retrieval intervals aligned with mailbox volume. This reduces duplicate processing and helps workflows remain reliable as email traffic increases.

Additional resources

• POP3 protocol (RFC 1939)