Devenia IMAP Intake

Ligue uma caixa IMAP ao seu plugin WordPress

Leia mensagens e anexos de uma caixa de correio IMAP existente através de uma interface PHP. O seu plugin decide quando lê e o que fazer com o resultado.

Versão 1.0.1 · GPL-2.0-or-later

Ilustração art déco de um recetor de correio com envelopes e um anexo.

Uma caixa, uma passagem clara

O seu plugin fornece o servidor, a porta, a pasta e as credenciais. O Devenia IMAP Intake abre a pasta em modo apenas de leitura através de uma ligação TLS verificada e devolve cabeçalhos, endereços dos remetentes e bytes descodificados dos anexos. A mensagem original permanece na pasta e o seu estado de leitura é preservado.

O seu plugin decide quando estabelecer ligação e é responsável pelo controlo de acesso, novas tentativas, deduplicação e armazenamento. Define também o tamanho máximo da mensagem completa em cada obtenção.

Leia a mensagem. O seu plugin trata do resto.

A mensagem permanece na caixa de correio. O recetor lê-a e descodifica os anexos; o seu plugin aplica as próprias regras e decide o que acontece a seguir.

Uma caixa IMAP fornece mensagens a um plugin WordPress através do Devenia IMAP Intake.

O recetor liga a caixa ao seu código; não decide como a mensagem é processada.

Exemplo: processar uma caixa partilhada

Imagine um plugin WordPress que processa mensagens enviadas para [email protected]. A pessoa responsável pelo desenvolvimento liga-o à caixa IMAP existente e define um tamanho máximo de mensagem. O recetor devolve mensagens e anexos; o plugin que o invoca verifica o que já foi tratado e decide como guardar ou processar cada elemento.

O exemplo é ilustrativo. O recetor é uma interface de leitura para programadores; não é um serviço de webmail e não envia correio por SMTP.

Use os identificadores no contexto correto

Os UID identificam mensagens apenas dentro de uma determinada conta, pasta e valor UIDVALIDITY. Compare o UIDVALIDITY atual com o valor guardado antes de reutilizar um cursor.

UIDVALIDITY

Identifica a série de UID atual da pasta selecionada.

UID

Identifica uma mensagem nessa conta, pasta e série de UID.

Requisitos e disponibilidade

Necessita do WordPress 6.9 ou posterior, PHP 8.1 ou posterior com OpenSSL e mbstring, certificados de autoridades de certificação fidedignas e um servidor IMAP com certificado TLS válido. A ligação suporta TLS implícito ou STARTTLS.

Descarregue o ZIP acima e teste a integração numa cópia de testes antes de a usar com uma caixa em produção.

No WordPress, abra Plugins → Adicionar novo plugin → Carregar plugin, escolha o ZIP, instale e ative o Devenia IMAP Intake. Invoque a interface a partir do seu próprio plugin depois de os plugins ativos serem carregados. Guarde as credenciais da caixa na configuração protegida da sua aplicação.

Abrir uma pasta e ler uma mensagem

Este exemplo utiliza um domínio reservado. Obtenha $password de uma configuração protegida e $saved_uid_validity da sua aplicação. Na primeira utilização, determine o UIDVALIDITY da pasta antes de guardar um cursor. fetch() aplica o limite de bytes à mensagem completa antes da descodificação.

use Devenia\ImapIntake\Mailbox;

$mailbox = Mailbox::open( array(
    'host'       => 'imap.example.com',
    'port'       => 993,
    'username'   => '[email protected]',
    'password'   => $password,
    'folder'     => 'INBOX',
    'encryption' => 'ssl',
    'timeout'    => 15,
) );

if ( is_wp_error( $mailbox ) ) {
    return $mailbox;
}

try {
    $validity = $mailbox->uid_validity();
    $uids = $mailbox->uids();
    if ( is_wp_error( $uids ) ) {
        return $uids;
    }

    if ( $validity !== $saved_uid_validity ) {
        return new WP_Error( 'mailbox_changed', 'Verifique o cursor guardado antes de continuar.' );
    }

    if ( $uids ) {
        $message = $mailbox->fetch( $uids[0], wp_max_upload_size() );
        if ( is_wp_error( $message ) ) {
            return $message;
        }
    }
} finally {
    $mailbox->close();
}

A interface disponibiliza Mailbox::open(), uid_validity(), uids(), fetch() e close(). Uma mensagem obtida inclui cabeçalhos, endereços dos remetentes e anexos com os respetivos bytes descodificados.

Num processo em produção, trate os erros, escolha o UID com o seu próprio cursor e valide os remetentes segundo as suas regras. Registe a conclusão apenas depois de os passos seguintes serem bem-sucedidos. Abra uma nova sessão após uma leitura IMAP falhada.

Se a ligação falhar, verifique o nome do servidor, a porta, o modo TLS, as credenciais e a cadeia de certificados de confiança. Se uma mensagem exceder o limite de bytes, decida como a aplicação deve tratá-la antes de tentar novamente.

Leia mensagens com o seu plugin WordPress

Descarregue o plugin, verifique os requisitos e teste a ligação com a sua aplicação.

Ilustração art déco de um recetor de correio com envelopes e um anexo.