imAPI

IMAP + SMTP bridge for MCP/automation workflows.

Use it to search, fetch, and manage email over IMAP, then send/reply over SMTP — with secrets-based auth and usage counters for billing.

Why imAPI

• One tool for both read (IMAP) and send (SMTP)
• Built for MCP/tooling workflows
• Bring-your-own mailbox credentials (no shared account lock-in)
• Returns usage counters in output (imapTouches, smtpRecipients)

Actions

• imap.list_folders
• imap.search
• imap.fetch
• imap.mark_read
• smtp.send
• smtp.reply

Quickstart (production-safe)

Use accountRef + env secrets (recommended), not raw credentials in run input.

1) Configure account secrets

Recommended: per-field env vars (most reliable in Apify UI)

For accountRef = main:

• IMAPI_MAIN_IMAP_HOST, IMAPI_MAIN_IMAP_PORT, IMAPI_MAIN_IMAP_SECURE, IMAPI_MAIN_IMAP_USER, IMAPI_MAIN_IMAP_PASSWORD
• IMAPI_MAIN_SMTP_HOST, IMAPI_MAIN_SMTP_PORT, IMAPI_MAIN_SMTP_SECURE, IMAPI_MAIN_SMTP_USER, IMAPI_MAIN_SMTP_PASSWORD

(Also supports fallback IMAPI_IMAP_* / IMAPI_SMTP_* for main.)

Optional: single JSON env var

IMAPI_ACCOUNTS_JSON is supported by code, but some users may find per-field env vars easier/more predictable in Apify Console.

{
  "main": {
    "imap": {
      "host": "imap.purelymail.com",
      "port": 993,
      "secure": true,
      "user": "you@example.com",
      "password": "..."
    },
    "smtp": {
      "host": "smtp.purelymail.com",
      "port": 465,
      "secure": true,
      "user": "you@example.com",
      "password": "..."
    }
  }
}

2) Run actions

Search inbox

{
  "action": "imap.search",
  "accountRef": "main",
  "query": {
    "folder": "INBOX",
    "unseen": true,
    "subject": "invoice",
    "limit": 20
  }
}

Fetch one message

{
  "action": "imap.fetch",
  "accountRef": "main",
  "folder": "INBOX",
  "uids": [12345]
}

Send email

{
  "action": "smtp.send",
  "accountRef": "main",
  "message": {
    "to": "team@example.com",
    "subject": "Status update",
    "text": "Hello from imAPI"
  }
}

Dry run (no send)

{
  "action": "smtp.send",
  "accountRef": "main",
  "dryRun": true,
  "message": {
    "to": "team@example.com",
    "subject": "Test",
    "text": "Preview only"
  }
}

Output shape

Successful output includes action result + usage counters:

{
  "ok": true,
  "data": { "...": "action result" },
  "usage": {
    "imapTouches": 1,
    "smtpRecipients": 0
  }
}

Error output:

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "uids are required"
  }
}

Safety and limits

Optional env controls:

• IMAPI_MAX_SMTP_RECIPIENTS_PER_RUN (default 200)
• IMAPI_ALLOWED_RECIPIENT_DOMAINS (comma-separated allowlist)

BYO credentials

imAPI users should always provide their own mailbox credentials via their own secrets/env vars.

Local development

npm i
npm run build
npm run test:live