Как закачать все письма с 1 янв. 2024 в cron с Imapflow

Самый быстрый и надёжный способ — дать Imapflow выполнить поиск по дате, а затем стримить результаты через fetch‑итератор. Это устраняет пропуски UID, избавляет от «пропущенных писем» и отлично работает в cron‑задачах.

Содержание

• Почему поиск по дате безопаснее, чем по message_id
• Подготовка клиента Imapflow для cron‑задачи
• Синтаксис поиска по диапазону дат
• Получение всех результатов через итератор
• Обработка пагинации и ошибок
• Полный пример для cron‑задачи Strapi
• Устранение распространённых проблем

Почему поиск по дате безопаснее, чем по message_id

На самом деле, message_id (заголовок RFC‑822 Message‑ID) является необязательным и может дублироваться или отсутствовать. Если полагаться на него, можно пропустить письма без ID или с одинаковым ID.
Поиск по SINCE/BEFORE гарантирует, что все сообщения в почтовом ящике, попадающие в диапазон, будут возвращены, независимо от заголовка Message‑ID.
Документация Imapflow подтверждает, что метод search принимает строки since и before в формате DD-MMM-YYYY и возвращает UID‑ы, удовлетворяющие критериям.

Подготовка клиента Imapflow для cron‑задачи

Создайте один постоянный клиент, который можно переиспользовать между запусками, если планировщик держит процесс живым.
Всегда захватывайте блокировку ящика перед запросом, чтобы избежать гонок.
Если соединение разорвалось, автоматически переподключайтесь; Imapflow бросает ConnectionError, который можно перехватить и повторить попытку.

import { ImapFlow } from 'imapflow';
import { simpleParser } from 'mailparser';

const client = new ImapFlow({
  host: 'imap.example.com',
  port: 993,
  secure: true,
  auth: { user: 'user@example.com', pass: 'app‑pw' },
});

async function ensureConnected() {
  if (!client.isConnected) await client.connect();
}

Синтаксис поиска по диапазону дат

Imapflow ожидает даты в формате DD-MMM-YYYY (например, 01-Jan-2024).
Чтобы охватить «1 января 2024 до сегодняшнего дня», задайте since этой датой и опустите before (или установите его в завтрашнюю дату, чтобы включить все письма до сегодняшнего дня).

const since = '01-Jan-2024';
const before = new Date();
before.setDate(before.getDate() + 1); // завтра
const beforeStr = `${before.getDate()}-${['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'][before.getMonth()]}-${before.getFullYear()}`;

const searchOpts = { since, before: beforeStr, all: true };

Флаг all: true заставляет Imapflow возвращать все совпадающие UID, даже если в ящике есть флаги, которые обычно бы их отфильтровали.

Получение всех результатов через итератор

Imapflow предоставляет асинхронный итератор (client.fetch), который стримит письма по одному, предотвращая переполнение памяти.

await client.getMailboxLock('INBOX');
try {
  for await (const msg of client.fetch(searchOpts, { source: true })) {
    const parsed = await simpleParser(msg.source);
    // Сохраняем или обрабатываем разобранное письмо
  }
} finally {
  client.releaseMailboxLock();
}

Если вам нужны только заголовки или флаги, замените source: true на, например, { envelope: true, flags: true }.

Обработка пагинации и ошибок

Пагинация: если в ящике тысячи писем, итератор автоматически справится с серверной пагинацией.
Обработка ошибок: оберните весь блок в try/catch.
ConnectionError: переподключитесь и повторите попытку.
FetchError: логируйте и пропускайте проблемное письмо.
TimeoutError: увеличьте client.timeout или прервите цикл и попробуйте позже.

try {
  // цикл fetch
} catch (err) {
  if (err.name === 'ConnectionError') {
    await client.connect();
    // При желании повторить fetch
  } else {
    console.error('Fetch error:', err);
  }
}

Полный пример для cron‑задачи Strapi

В Strapi 5.18.1 можно добавить cron‑задачу в config/functions/cron.js:

// config/functions/cron.js
module.exports = () => {
  const { ImapFlow } = require('imapflow');
  const { simpleParser } = require('mailparser');

  const client = new ImapFlow({
    host: process.env.IMAP_HOST,
    port: 993,
    secure: true,
    auth: { user: process.env.IMAP_USER, pass: process.env.IMAP_PASS },
  });

  async function fetchOldEmails() {
    await client.connect();
    await client.getMailboxLock('INBOX');

    const since = '01-Jan-2024';
    const before = new Date();
    before.setDate(before.getDate() + 1);
    const beforeStr = `${before.getDate()}-${['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'][before.getMonth()]}-${before.getFullYear()}`;

    const searchOpts = { since, before: beforeStr, all: true };

    try {
      for await (const msg of client.fetch(searchOpts, { source: true })) {
        const parsed = await simpleParser(msg.source);
        // Пример: создать запись в Strapi
        await strapi.entityService.create('api::email.email', {
          data: {
            subject: parsed.subject,
            from: parsed.from.text,
            date: parsed.date,
            body: parsed.text,
          },
        });
      }
    } catch (e) {
      strapi.log.error('Imapflow fetch error:', e);
    } finally {
      client.releaseMailboxLock();
      await client.logout();
    }
  }

  // Запуск каждый день в 02:00
  strapi.cron.schedule('0 2 * * *', fetchOldEmails);
};

Убедитесь, что переменные окружения с учётными данными IMAP заданы.

Устранение распространённых проблем

Итог

Используя поиск по дате с since/before и стриминг через асинхронный итератор Imapflow, вы надёжно получите каждое письмо с 1 января 2024 до настоящего момента, не пропуская и не дублируя. Встраиванием логики в cron‑задачу Strapi, автоматическим переподключением и надёжной обработкой ошибок вы получите устойчивое и поддерживаемое решение.

Источники

1. Imapflow – Module documentation
2. Imapflow GitHub repository
3. Imapflow – Searching Messages
4. Imapflow – Fetching Messages
5. Strapi – Cron Jobs