shade-plugins-email 0.1.0__py3-none-any.whl

shade_plugins_email/__init__.py

@@ -0,0 +1,407 @@
+"""O plugin ``email``: ler por IMAP e enviar por SMTP sob o contrato de plugin do shade-sdk.
+
+```toml
+[config]
+email_imap = "imap.empresa.com.br"
+email_smtp = "smtp.empresa.com.br"
+
+[hosts]
+permitidos = ["imap.empresa.com.br", "smtp.empresa.com.br"]
+
+[credenciais]
+nomes = ["EMAIL_USUARIO", "EMAIL_SENHA"]
+
+[plugins]
+email = "0.1.0"
+```
+
+```python
+import shade_plugins_email as email
+
+for msg in email.buscar(nao_lidas=True, assunto="pedido"):
+    email.baixar_anexos(item, msg["uid"])
+
+with item.efetivar("avisar o cliente"):
+    email.enviar(para="cliente@exemplo.com", assunto="Pedido recebido", corpo="...")
+```
+
+- **Servidor do projeto:** o IMAP e o SMTP vêm de ``[config] email_imap`` e ``email_smtp`` e
+  têm de estar em ``[hosts] permitidos``; nem argumento nem item escolhem outro servidor. O
+  usuário e a senha vêm só de ``EMAIL_USUARIO`` e ``EMAIL_SENHA``.
+- **TLS obrigatório:** na conexão (``tls="implicito"``, IMAP 993 e SMTP 465, o padrão) ou por
+  STARTTLS (``tls="starttls"``, 143 e 587). O certificado é verificado; o servidor sem STARTTLS
+  é recusado antes do login (``TlsObrigatorio``).
+- **No executor da plataforma:** a conexão sai pelo proxy do sandbox (``SHADE_TUNEL_DO_PLUGIN``),
+  só nas portas 993, 465 e 587 dos hosts de ``[config]``; outra porta é ``ForaDoEgresso``. Fora
+  do sandbox a conexão é direta (o ``HTTPS_PROXY`` não é usado).
+- **Ler não muda nada:** a caixa abre só para leitura e a mensagem é lida sem marcar como lida.
+- **Enviar só dentro de** ``item.efetivar()`` (no ensaio não roda). O ``Message-ID`` deriva da
+  chave do item, do nome da efetivação e da ordem do envio no bloco: o mesmo em toda execução.
+  A conexão e o login são tentados de novo na falha de rede; depois que a mensagem começou a ir,
+  nunca (``EnvioIncerto``).
+- **Prazo:** ``timeout=`` (30 s) vale para a chamada inteira, retentativas incluídas.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import datetime as dt
+import os
+import re
+import smtplib
+import ssl
+from base64 import b64encode
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+from shade_sdk.plugins import Plugin
+
+from shade_plugins_email import _imap, _mensagem
+from shade_plugins_email._rede import (
+    TLS_NA_CONEXAO,
+    TLS_POR_STARTTLS,
+    Prazo,
+    Smtp,
+    SmtpSsl,
+    antes_do_envio,
+    contexto_tls,
+    porta_padrao,
+)
+from shade_plugins_email.erros import (
+    EnvioIncerto,
+    EnvioNaoSaiu,
+    ErroDoEmail,
+    ForaDoEgresso,
+    MensagemNaoEncontrada,
+    TlsObrigatorio,
+)
+
+__version__ = "0.1.0"
+
+#: As chaves de ``[config]`` com os servidores do cliente.
+IMAP = "email_imap"
+SMTP = "email_smtp"
+#: As credenciais que o plugin lê (``[credenciais] nomes``).
+USUARIO = "EMAIL_USUARIO"
+SENHA = "EMAIL_SENHA"
+#: Quantas mensagens ``buscar`` devolve, no máximo.
+LIMITE_MAX = 500
+#: O nome com que o robô se apresenta ao SMTP: não o nome da máquina.
+NOME_NO_EHLO = "localhost"
+_CONTROLE = re.compile(r"[\x00-\x1f\x7f]")
+
+PLUGIN = Plugin(
+    "email",
+    __version__,
+    shade_sdk=">=0.22.1,<0.23",
+    dono="Equipe de integrações da ShadeOne",
+    hosts_do_projeto=[IMAP, SMTP],
+    credenciais=[USUARIO, SENHA],
+)
+
+__all__ = [
+    "PLUGIN",
+    "EnvioIncerto",
+    "EnvioNaoSaiu",
+    "ErroDoEmail",
+    "ForaDoEgresso",
+    "MensagemNaoEncontrada",
+    "TlsObrigatorio",
+    "baixar_anexos",
+    "buscar",
+    "enviar",
+]
+
+
+def _credenciais(chamada: Any) -> tuple[str, str]:
+    usuario, senha = chamada.segredo(USUARIO), chamada.segredo(SENHA)
+    if _CONTROLE.search(usuario) or _CONTROLE.search(senha):
+        raise ValueError(f"{USUARIO} e {SENHA} não podem ter quebra de linha nem controle")
+    return usuario, senha
+
+
+def _conectar_imap(chamada: Any, porta: Any, tls: str) -> tuple[Any, Prazo]:
+    porta = porta_padrao(porta, tls, 993, 143)
+    host = chamada.host_do_projeto(IMAP)
+    usuario, senha = _credenciais(chamada)
+    prazo = Prazo(chamada.timeout)
+    try:
+        return _imap.conectar(host, porta, tls, usuario, senha, prazo), prazo
+    except TlsObrigatorio:
+        raise
+    except _imap.imaplib.IMAP4.abort as exc:
+        raise ErroDoEmail("IMAP: a conexão caiu antes do login") from exc
+    except _imap.imaplib.IMAP4.error as exc:
+        raise ErroDoEmail("IMAP: o servidor recusou o login") from exc
+    except (OSError, ssl.SSLError) as exc:
+        raise ErroDoEmail(f"IMAP: a conexão não abriu ({type(exc).__name__})") from exc
+
+
+def _lendo(funcao: Any) -> Any:
+    """A falha de rede ou de protocolo no meio da leitura vira ``ErroDoEmail``."""
+    try:
+        return funcao()
+    except ErroDoEmail:
+        raise
+    except _imap.imaplib.IMAP4.error as exc:
+        raise ErroDoEmail(f"IMAP: o servidor recusou o comando ({type(exc).__name__})") from exc
+    except (OSError, ssl.SSLError) as exc:
+        raise ErroDoEmail(f"IMAP: a conexão caiu ({type(exc).__name__})") from exc
+
+
+@PLUGIN.operacao
+def buscar(
+    chamada: Any,
+    caixa: str = "INBOX",
+    *,
+    nao_lidas: bool = False,
+    de: str | None = None,
+    assunto: str | None = None,
+    desde: dt.date | None = None,
+    limite: int = 50,
+    porta: int | None = None,
+    tls: str = TLS_NA_CONEXAO,
+) -> list[dict[str, Any]]:
+    """As mensagens da ``caixa``, da mais nova à mais antiga, até ``limite``: só as não lidas,
+    as de um remetente ou com um trecho no assunto (sem diferenciar maiúsculas), a partir de uma
+    data. Cada uma: ``uid``, ``message_id``, ``de``, ``para``, ``cc``, ``assunto``, ``data``,
+    ``tamanho``, ``texto``, ``html``, ``anexos`` (nome, tipo, tamanho) e ``corpo_omitido`` (a
+    mensagem acima de 25 MiB vem só com o cabeçalho). Nada é marcado como lido."""
+    nome_da_caixa = _imap.caixa_quotada(caixa)
+    filtro = _imap.criterios(bool(nao_lidas), desde)
+    for valor, campo in ((de, "de"), (assunto, "assunto")):
+        if valor is not None:
+            _mensagem.sem_quebra(valor, campo)
+    if not isinstance(limite, int) or isinstance(limite, bool) or not 0 < limite <= LIMITE_MAX:
+        raise ValueError(f"limite é um número de 1 a {LIMITE_MAX}")
+    conexao, prazo = _conectar_imap(chamada, porta, tls)
+    try:
+
+        def ler() -> list[dict[str, Any]]:
+            _imap.abrir_caixa(conexao, nome_da_caixa, prazo)
+            uids = _imap.buscar_uids(conexao, filtro, prazo)
+            escolhidos: list[tuple[int, int, bytes]] = []
+            for lote in _imap.em_lotes(uids):
+                vistos = _imap.cabecalhos(conexao, lote, prazo)
+                for uid in lote:
+                    if uid in vistos and _mensagem.casa(vistos[uid][1], de, assunto):
+                        escolhidos.append((uid, *vistos[uid]))
+                    if len(escolhidos) >= limite:
+                        break
+                if len(escolhidos) >= limite:
+                    break
+            resultado = []
+            for uid, tamanho, cabecalho in escolhidos:
+                dados = None
+                if tamanho <= _imap.MENSAGEM_MAX_BYTES:
+                    dados = _imap.mensagem(conexao, uid, prazo)
+                resultado.append(_mensagem.descrever(str(uid), dados, cabecalho, tamanho))
+            return resultado
+
+        return _lendo(ler)
+    finally:
+        _imap.fechar(conexao)
+
+
+def _pasta_do_workdir(pasta: Any) -> Path:
+    if not isinstance(pasta, str) or not pasta.strip():
+        raise ValueError("pasta é um caminho relativo ao diretório de trabalho, como 'anexos'")
+    relativa = Path(pasta)
+    if relativa.is_absolute() or ".." in relativa.parts:
+        raise ValueError("pasta é um caminho relativo ao diretório de trabalho, sem '..'")
+    return Path.cwd().resolve() / relativa
+
+
+@PLUGIN.operacao
+def baixar_anexos(
+    chamada: Any,
+    item: Any,
+    uid: str | int,
+    *,
+    caixa: str = "INBOX",
+    nomes: Iterable[str] | None = None,
+    pasta: str = "anexos",
+    porta: int | None = None,
+    tls: str = TLS_NA_CONEXAO,
+) -> list[dict[str, Any]]:
+    """Os anexos da mensagem ``uid`` (de ``buscar``) gravados em ``<pasta>/<uid>/`` no
+    diretório de trabalho e anexados ao item por ``item.anexar`` (a saída do run). ``nomes``
+    escolhe quais. Cada um: ``nome`` (o da mensagem), ``arquivo`` (o caminho gravado, com o nome
+    limpo de separador e controle), ``tipo``, ``tamanho`` e ``anexado`` (``False`` acima do teto
+    da saída do run; o arquivo fica no disco). A mensagem não é marcada como lida."""
+    anexar = getattr(item, "anexar", None)
+    if not callable(anexar):
+        raise TypeError("baixar_anexos(item, uid): passe o item do processar()")
+    texto_do_uid = str(uid)
+    if isinstance(uid, bool) or not texto_do_uid.isdigit() or not texto_do_uid.isascii():
+        raise ValueError("uid é o número que buscar() devolve")
+    escolhidos = None if nomes is None else ({nomes} if isinstance(nomes, str) else set(nomes))
+    nome_da_caixa = _imap.caixa_quotada(caixa)
+    destino = _pasta_do_workdir(pasta) / texto_do_uid
+    conexao, prazo = _conectar_imap(chamada, porta, tls)
+    try:
+
+        def ler() -> bytes | None:
+            _imap.abrir_caixa(conexao, nome_da_caixa, prazo)
+            return _imap.mensagem(conexao, int(texto_do_uid), prazo)
+
+        dados = _lendo(ler)
+    finally:
+        _imap.fechar(conexao)
+    if dados is None:
+        raise MensagemNaoEncontrada(f"IMAP: a mensagem {texto_do_uid} não está na caixa")
+    raiz = Path.cwd().resolve()
+    usados: set[str] = set()
+    resultado = []
+    for ordem, parte in enumerate(_mensagem.partes_anexadas(_mensagem.ler_bytes(dados)), start=1):
+        nome = _mensagem.nome_do_anexo(parte)
+        if escolhidos is not None and nome not in escolhidos:
+            continue
+        conteudo = parte.get_payload(decode=True) or b""
+        destino.mkdir(parents=True, exist_ok=True)
+        caminho = destino / _mensagem.nome_seguro(nome, usados, ordem)
+        caminho.write_bytes(conteudo)
+        resultado.append(
+            {
+                "nome": nome,
+                "arquivo": str(caminho.relative_to(raiz)),
+                "tipo": parte.get_content_type(),
+                "tamanho": len(conteudo),
+                "anexado": bool(anexar(caminho)),
+            }
+        )
+    return resultado
+
+
+def _abrir_smtp(host: str, porta: int, tls: str, usuario: str, senha: str, prazo: Prazo) -> Any:
+    contexto = contexto_tls()
+    if tls == TLS_NA_CONEXAO:
+        conexao: smtplib.SMTP = SmtpSsl(
+            host, porta, local_hostname=NOME_NO_EHLO, context=contexto, timeout=prazo.restante()
+        )
+    else:
+        conexao = Smtp(host, porta, local_hostname=NOME_NO_EHLO, timeout=prazo.restante())
+    try:
+        prazo.no_socket(conexao.sock)
+        conexao.ehlo()
+        if tls == TLS_POR_STARTTLS:
+            if not conexao.has_extn("starttls"):
+                raise TlsObrigatorio(
+                    "SMTP: o servidor não oferece STARTTLS; a senha não sai em texto aberto"
+                )
+            conexao.starttls(context=contexto)
+            prazo.no_socket(conexao.sock)
+            conexao.ehlo()
+        if usuario.isascii() and senha.isascii():
+            conexao.login(usuario, senha)
+        else:
+            # O ``login`` do smtplib codifica em ASCII; o AUTH PLAIN aceita UTF-8.
+            plano = b64encode(f"\0{usuario}\0{senha}".encode()).decode("ascii")
+            codigo, resposta = conexao.docmd("AUTH", "PLAIN " + plano)
+            if codigo != 235:
+                raise smtplib.SMTPAuthenticationError(codigo, resposta)
+        return conexao
+    except BaseException:
+        _fechar_smtp(conexao)
+        raise
+
+
+def _fechar_smtp(conexao: Any) -> None:
+    if conexao is None:
+        return
+    try:
+        conexao.quit()
+    except Exception:
+        with contextlib.suppress(Exception):
+            conexao.close()
+
+
+@PLUGIN.efeito
+def enviar(
+    chamada: Any,
+    para: str | Iterable[str],
+    assunto: str,
+    corpo: str,
+    *,
+    cc: str | Iterable[str] | None = None,
+    cco: str | Iterable[str] | None = None,
+    de: str | None = None,
+    html: str | None = None,
+    anexos: Iterable[str | os.PathLike[str]] = (),
+    em_resposta_a: str | None = None,
+    porta: int | None = None,
+    tls: str = TLS_NA_CONEXAO,
+) -> dict[str, Any]:
+    """Envia uma mensagem (só dentro de ``item.efetivar()``). ``de`` é o remetente (o
+    ``EMAIL_USUARIO``, se omitido); ``cco`` vai no envelope, nunca no cabeçalho; ``anexos`` são
+    arquivos do diretório de trabalho (até 20 MiB somados); ``em_resposta_a`` é o ``message_id``
+    da mensagem respondida. Devolve ``message_id`` e ``recusados`` (os destinatários que o
+    servidor recusou, quando aceitou os outros).
+
+    ``EnvioNaoSaiu`` (um ``http.NadaSaiu``): o servidor não aceitou a mensagem.
+    ``EnvioIncerto``: a mensagem começou a ir e a confirmação não chegou; não é repetida."""
+    porta = porta_padrao(porta, tls, 465, 587)
+    destino_para = _mensagem.enderecos(para, "para")
+    destino_cc = _mensagem.enderecos(cc, "cc")
+    destino_cco = _mensagem.enderecos(cco, "cco")
+    if not destino_para:
+        raise ValueError("para: ao menos um destinatário")
+    todos = [*destino_para, *destino_cc, *destino_cco]
+    if len(todos) > _mensagem.DESTINATARIOS_MAX:
+        raise ValueError(f"no máximo {_mensagem.DESTINATARIOS_MAX} destinatários por mensagem")
+    _mensagem.sem_quebra(assunto, "assunto")
+    if not isinstance(corpo, str) or (html is not None and not isinstance(html, str)):
+        raise TypeError("corpo e html são texto")
+    lista_de_anexos = [anexos] if isinstance(anexos, str | os.PathLike) else list(anexos)
+    arquivos = [_mensagem.arquivo_do_workdir(a) for a in lista_de_anexos]
+    referencia = None
+    if em_resposta_a is not None:
+        referencia = _mensagem.referencia(em_resposta_a, "em_resposta_a")
+    host = chamada.host_do_projeto(SMTP)
+    usuario, senha = _credenciais(chamada)
+    remetente = _mensagem.endereco(de if de is not None else usuario, "de")
+    mensagem = _mensagem.montar(
+        remetente=remetente,
+        para=destino_para,
+        cc=destino_cc,
+        assunto=assunto,
+        corpo=corpo,
+        html=html,
+        anexos=arquivos,
+        em_resposta_a=referencia,
+        chave=chamada.idempotencia,
+    )
+    prazo = Prazo(chamada.timeout)
+    try:
+        conexao = antes_do_envio(
+            lambda: _abrir_smtp(host, porta, tls, usuario, senha, prazo), prazo
+        )
+    except smtplib.SMTPAuthenticationError as exc:
+        raise EnvioNaoSaiu("SMTP: o servidor recusou o login") from exc
+    except (TlsObrigatorio, ForaDoEgresso) as exc:
+        raise EnvioNaoSaiu(str(exc)) from exc
+    except (OSError, ssl.SSLError, smtplib.SMTPException) as exc:
+        raise EnvioNaoSaiu(f"SMTP: a conexão não abriu ({type(exc).__name__})") from exc
+    try:
+        prazo.no_socket(conexao.sock)
+    except TimeoutError as exc:
+        _fechar_smtp(conexao)
+        raise EnvioNaoSaiu("SMTP: o prazo acabou antes do envio") from exc
+    # Daqui em diante, nenhuma retentativa: a mensagem pode chegar ao servidor.
+    try:
+        recusados = conexao.send_message(
+            mensagem, from_addr=remetente[1], to_addrs=[addr for _, addr in todos]
+        )
+    except (smtplib.SMTPRecipientsRefused, smtplib.SMTPSenderRefused) as exc:
+        raise EnvioNaoSaiu("SMTP: o servidor recusou o remetente ou os destinatários") from exc
+    except smtplib.SMTPDataError as exc:
+        raise EnvioNaoSaiu(f"SMTP: o servidor recusou a mensagem ({exc.smtp_code})") from exc
+    except (OSError, ssl.SSLError, smtplib.SMTPException) as exc:
+        raise EnvioIncerto(
+            f"SMTP: a conexão caiu durante o envio ({type(exc).__name__}); a mensagem pode ter "
+            "saído e não é repetida"
+        ) from exc
+    finally:
+        _fechar_smtp(conexao)
+    return {"message_id": str(mensagem["Message-ID"]), "recusados": sorted(recusados)}

shade_plugins_email/_imap.py

@@ -0,0 +1,196 @@
+"""O lado IMAP: conectar com TLS, abrir a caixa só para leitura e baixar sem marcar como lida.
+
+Nenhum texto do robô vira comando: a caixa entra codificada (UTF-7 modificado) e entre aspas, a
+busca no servidor usa só critérios montados aqui (``UNSEEN``, ``SINCE`` com a data formatada), e
+o filtro de remetente e assunto roda no cliente. A caixa é aberta por ``EXAMINE`` e a mensagem é
+lida por ``BODY.PEEK``: buscar não muda a marca de lida de nada.
+"""
+
+from __future__ import annotations
+
+import base64
+import contextlib
+import datetime as dt
+import imaplib
+import re
+from collections.abc import Iterator, Sequence
+from typing import Any
+
+from shade_plugins_email._rede import (
+    TLS_NA_CONEXAO,
+    Imap,
+    ImapSsl,
+    Prazo,
+    antes_do_envio,
+    contexto_tls,
+)
+from shade_plugins_email.erros import ErroDoEmail, TlsObrigatorio
+
+#: Quantas mensagens cada ``FETCH`` de cabeçalhos pede.
+LOTE = 50
+#: A mensagem acima disto vem só com o cabeçalho (``corpo_omitido``).
+MENSAGEM_MAX_BYTES = 25 * 1024 * 1024
+_MESES = ("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec")
+_INICIO_DE_RESPOSTA = re.compile(rb"^\d+ \(")
+_UID = re.compile(rb"\bUID (\d+)")
+_TAMANHO = re.compile(rb"\bRFC822\.SIZE (\d+)")
+_CONTROLE = re.compile(r"[\x00-\x1f\x7f]")
+
+
+def caixa_quotada(nome: Any) -> str:
+    """O nome da caixa como argumento IMAP: UTF-7 modificado (RFC 3501, 5.1.3) entre aspas."""
+    if not isinstance(nome, str) or not nome or len(nome) > 200 or _CONTROLE.search(nome):
+        raise ValueError("caixa é o nome da pasta (INBOX, Notas), sem caractere de controle")
+    partes: list[str] = []
+    fora: list[str] = []
+
+    def fechar() -> None:
+        if fora:
+            bruto = base64.b64encode("".join(fora).encode("utf-16-be")).rstrip(b"=")
+            partes.append("&" + bruto.replace(b"/", b",").decode("ascii") + "-")
+            fora.clear()
+
+    for caractere in nome:
+        if 0x20 <= ord(caractere) <= 0x7E:
+            fechar()
+            partes.append("&-" if caractere == "&" else caractere)
+        else:
+            fora.append(caractere)
+    fechar()
+    texto = "".join(partes)
+    return '"' + texto.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def criterios(nao_lidas: bool, desde: Any) -> list[str]:
+    resultado: list[str] = []
+    if nao_lidas:
+        resultado.append("UNSEEN")
+    if desde is not None:
+        if not isinstance(desde, dt.date):
+            raise TypeError("desde é uma data (datetime.date)")
+        resultado += ["SINCE", f"{desde.day:02d}-{_MESES[desde.month - 1]}-{desde.year:04d}"]
+    return resultado or ["ALL"]
+
+
+def _quotar(texto: str) -> str:
+    return '"' + texto.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def _entrar(conexao: imaplib.IMAP4, usuario: str, senha: str) -> None:
+    if usuario.isascii() and senha.isascii() and "LOGINDISABLED" not in conexao.capabilities:
+        # O ``login`` do imaplib põe a senha entre aspas, mas não o usuário.
+        conexao.login(_quotar(usuario), senha)
+        return
+    plano = f"\0{usuario}\0{senha}".encode()
+    conexao.authenticate("PLAIN", lambda _desafio: plano)
+
+
+def fechar(conexao: imaplib.IMAP4 | None) -> None:
+    if conexao is None:
+        return
+    try:
+        conexao.logout()
+    except Exception:
+        with contextlib.suppress(Exception):
+            conexao.shutdown()
+
+
+def conectar(
+    host: str, porta: int, tls: str, usuario: str, senha: str, prazo: Prazo
+) -> imaplib.IMAP4:
+    contexto = contexto_tls()
+
+    def abrir() -> imaplib.IMAP4:
+        if tls == TLS_NA_CONEXAO:
+            conexao: imaplib.IMAP4 = ImapSsl(
+                host, porta, ssl_context=contexto, timeout=prazo.restante()
+            )
+        else:
+            conexao = Imap(host, porta, timeout=prazo.restante())
+        try:
+            if tls != TLS_NA_CONEXAO:
+                if "STARTTLS" not in conexao.capabilities:
+                    raise TlsObrigatorio(
+                        "IMAP: o servidor não oferece STARTTLS; a senha não sai em texto aberto"
+                    )
+                prazo.no_socket(conexao.sock)
+                conexao.starttls(ssl_context=contexto)
+            prazo.no_socket(conexao.sock)
+            _entrar(conexao, usuario, senha)
+        except BaseException:
+            fechar(conexao)
+            raise
+        return conexao
+
+    return antes_do_envio(abrir, prazo)
+
+
+def abrir_caixa(conexao: imaplib.IMAP4, caixa: str, prazo: Prazo) -> None:
+    prazo.no_socket(conexao.sock)
+    status, _ = conexao.select(caixa, readonly=True)
+    if status != "OK":
+        raise ErroDoEmail("IMAP: a caixa não existe ou não pode ser lida")
+
+
+def buscar_uids(conexao: imaplib.IMAP4, filtro: Sequence[str], prazo: Prazo) -> list[int]:
+    """Os UIDs que casam, do mais novo ao mais antigo."""
+    prazo.no_socket(conexao.sock)
+    status, dados = conexao.uid("SEARCH", *filtro)
+    if status != "OK":
+        raise ErroDoEmail("IMAP: o servidor recusou a busca")
+    numeros = b" ".join(d for d in dados if isinstance(d, bytes)).split()
+    return sorted({int(n) for n in numeros if n.isdigit()}, reverse=True)
+
+
+def _respostas(dados: Sequence[Any]) -> Iterator[tuple[bytes, bytes | None]]:
+    """Cada resposta do ``FETCH``: (o texto dela, sem o literal; o literal)."""
+    atual: list[Any] | None = None
+    for parte in dados:
+        if isinstance(parte, tuple):
+            if atual is not None:
+                yield atual[0], atual[1]
+            atual = [parte[0], parte[1]]
+        elif isinstance(parte, bytes):
+            if _INICIO_DE_RESPOSTA.match(parte):
+                if atual is not None:
+                    yield atual[0], atual[1]
+                atual = [parte, None]
+            elif atual is not None:
+                atual[0] += parte
+    if atual is not None:
+        yield atual[0], atual[1]
+
+
+def _buscar(conexao: imaplib.IMAP4, uids: str, itens: str, prazo: Prazo) -> Sequence[Any]:
+    prazo.no_socket(conexao.sock)
+    status, dados = conexao.uid("FETCH", uids, itens)
+    if status != "OK":
+        raise ErroDoEmail("IMAP: o servidor recusou a leitura")
+    return dados
+
+
+def cabecalhos(
+    conexao: imaplib.IMAP4, uids: Sequence[int], prazo: Prazo
+) -> dict[int, tuple[int, bytes]]:
+    """UID → (tamanho, cabeçalho), sem marcar como lida."""
+    resultado: dict[int, tuple[int, bytes]] = {}
+    dados = _buscar(conexao, ",".join(map(str, uids)), "(UID RFC822.SIZE BODY.PEEK[HEADER])", prazo)
+    for texto, literal in _respostas(dados):
+        uid, tamanho = _UID.search(texto), _TAMANHO.search(texto)
+        if uid and literal is not None:
+            resultado[int(uid[1])] = (int(tamanho[1]) if tamanho else len(literal), literal)
+    return resultado
+
+
+def mensagem(conexao: imaplib.IMAP4, uid: int, prazo: Prazo) -> bytes | None:
+    """A mensagem inteira, sem marcar como lida; ``None`` se o UID não existe."""
+    for texto, literal in _respostas(_buscar(conexao, str(uid), "(UID BODY.PEEK[])", prazo)):
+        achado = _UID.search(texto)
+        if achado and int(achado[1]) == uid and literal is not None:
+            return literal
+    return None
+
+
+def em_lotes(uids: Sequence[int]) -> Iterator[Sequence[int]]:
+    for inicio in range(0, len(uids), LOTE):
+        yield uids[inicio : inicio + LOTE]