Documentação & Enciclopédia do Sistema

O MarbleSend opera com um único executor mestre em segundo plano: worker.php. O dashboard inspeciona cm_settings['worker_last_run'] para determinar se o cron está disparando a cada 60 segundos.

O visualizador de crescimento renderiza a distribuição de volume em quatro intervalos selecionáveis: 7 dias, 30 dias, 90 dias e no ano até a data (YTD). Cada barra representa um bloco de tempo agregado, exibindo contagem de envios e aberturas ao passar o cursor.

A coluna da direita exibe os disparos recentes de Campaign em tempo real com emblemas animados (Completed, Sending pulsante, Failed, Draft), taxas de entrega e cartão de atividade do worker.

A tabela de auditoria inferior lista as transmissões recentes com metadados: nome da Campaign, status, origem (manual, schedule, rss, auto_resend), proporção de destinatários atendidos e taxa de abertura apurada.

Quando o domínio de envio não possui records SPF, DKIM ou DMARC verificados, o MarbleSend destaca um banner de atenção logo acima das métricas de KPI. Clicar em Verificar DNS do domínio abre o assistente de diagnóstico de 4 etapas em /settings?tab=deliverability, evitando que usuários prejudiquem a reputação do domínio com caixas postais não autenticadas.

Acessos diretos para conectar o painel aos processos essenciais: boletins periódicos automatizados, digests de fontes RSS para e-mail, importação de contatos, double opt-in e supressão de endereços.

Sempre que uma transmissão estiver em envio ativo, um banner de monitoramento fixo desliza para a parte superior de /campaigns. Ele consulta /api/campaigns/:id/progress a cada 1,5 segundo sem recarregar a página.

A coluna esquerda permite a segmentação precisa de assinantes. Os administradores podem filtrar por tags personalizadas de contato, pesquisar por e-mail/nome parcial e selecionar contatos individuais ou clicar em Selecionar todos os correspondentes.

Para evitar erros graves (como envio de e-mails com placeholders quebrados, links de descadastro ausentes ou gatilhos de spam), o MarbleSend exige uma verificação preflight antes do disparo.

Antes de enviar milhares de e-mails para a fila, o botão Enviar e-mail de teste dispara uma mensagem de teste única diretamente para o administrador ou caixa de QA sem alterar a lista de destinatários no banco de dados. Todas as tags de placeholder ({{first_name}}, {{email}}, {{unsubscribe_link}}) são preenchidas com valores de simulação para você inspecionar a renderização no Gmail, Apple Mail e Outlook.

Todas as tags de link de saída (<a href="...">) são processadas por App\Services\TrackingInjector. Os parâmetros UTM (utm_source, utm_medium, utm_campaign, utm_content) são anexados automaticamente antes do encapsulamento de redirecionamento de clique. Links mailto, tel e de cancelamento são mantidos intactos.

O portfólio de histórico completo oferece filtragem multiatributo por origem (manual, recurring, rss, resend_unopened), status (completed, sending, failed, draft) e intervalo de datas. Os administradores podem selecionar múltiplas Campaigns para baixar logs agregados de entrega em CSV.

Em /campaigns/:id/report, o MarbleSend apresenta um relatório pós-Campaign abrangente:

Repositório unificado para todos os templates de marketing, transacionais e autoresponders. Oferece busca rápida no navegador, slugs imutáveis e status de rascunho em tempo real.

Aplicações de email convencionais (como o Microsoft Outlook sob o renderizador Word HTML) não aceitam CSS Grid ou Flexbox. O MarbleSend inclui 8 layouts estruturados em tabelas testados no Gmail, Outlook, Apple Mail e Yahoo:

Um ambiente enxuto para criação de emails com controle de Tabulação, contagem de caracteres em tempo real e organizador automático de espaçamentos.

Emula leitores de desktop e celulares em um iframe sandbox com proteção de isolamento, resguardando o painel de controle de estilos externos.

No momento do envio, o motor de modelos substitui dinamicamente os tokens por atributos do destinatário, links de rastreamento seguros, resumos de artigos RSS e Publicações de notícias.

Recurso prático para despachar mensagens de teste para qualquer endereço usando o perfil SMTP desejado antes do agendamento ou transmissão.

Assistente de redação nativo operando diretamente via BYOK (Bring Your Own Key) para elaborar e aperfeiçoar templates de alta conversão sem intermediários.

Avalia os assuntos de toda a biblioteca, estimando índice de abertura, riscos de palavras-gatilho de spam e limites de caracteres com alternativas em 1 clique.

Escreva artigos na aba Publicações de Modelos (Markdown com pré-visualização ao vivo). Um agendamento de Newsletter definido como “Publicações de notícias” envia cada publicação Pronta uma única vez, da mais antiga para a mais recente, preenchendo o marcador {{news_posts}} do seu modelo. As publicações existem apenas no seu e-mail — não há página pública.

O MarbleSend oferece duas visualizações operacionais sincronizadas para diferentes fluxos de trabalho: um gerenciador compacto em grade Bento (/schedules) e um calendário mensal interativo amplo (/schedules/list).

Os agendamentos recorrentes utilizam SchedulerService::computeNextRun(), substituindo cálculos manuais de timestamp por matemática precisa com DateTimeImmutable do PHP.

O MarbleSend conecta-se diretamente ao feed do seu blog usando SimpleXML e cURL nativos, convertendo novos posts em Campaign automatizadas sem ferramentas de integração externas.

Diferente de snapshots estáticos de Campaign, envios agendados resolvem suas listas de destinatários dinamicamente no segundo exato em que a ocorrência dispara.

Cada execução automatizada gera um registro imutável em cm_schedule_occurrences, detalhando horários, resultados, contagem de destinatários e telemetria de erros.

Administradores podem contornar a contagem regressiva e disparar imediatamente um envio avulso de qualquer agendamento com a ação "Trigger Send Now".

O MarbleSend conta com um perímetro de simultaneidade empresarial desenvolvido para evitar envios duplicados em servidores de hospedagem compartilhada.

O card dinâmico Optimization Tip na tela Schedules apresenta 8 recomendações operacionais comprovadas em produção para envios confiáveis em hospedagem compartilhada:

Um agendamento de Newsletter agora pode enviar artigos em vez de um modelo fixo. Defina Origem do conteúdo como “Publicações de notícias” e cada execução entrega as próximas Publicações Prontas de Modelos → Publicações, inseridas no modelo por {{news_posts}}. Nada é enviado quando nenhuma publicação está esperando.

1. 1Abra Modelos → Publicações e escreva seu artigo em Markdown.
2. 2Crie ou abra um modelo e coloque {{news_posts}} onde os artigos devem aparecer (o modelo inicial “Newsletter de publicações de notícias” já o contém).
3. 3Abra Agendamentos → Novo, mantenha o tipo em Newsletter e defina Origem do conteúdo como “Publicações de notícias”.
4. 4Escolha o modelo, o público, o perfil SMTP, as publicações por e-mail (1–20) e a cadência.
5. 5Salve. Somente publicações que ficarem Prontas depois deste momento podem ser enviadas por este agendamento.
6. 6Marque a publicação como Pronta. A próxima ocorrência — ou Executar agora — a envia.

• Mudar um agendamento de Somente modelo para Publicações de notícias define uma nova data de corte nesse momento; voltar a apaga.
• Salvar o formulário do agendamento verifica de novo se o modelo contém {{news_posts}}. Pausar e Retomar apenas alternam o interruptor de ligado/desligado e nunca verificam, então você sempre pode pausar.
• Supressão Inteligente é desativada automaticamente no modo Publicações de notícias: ela excluiria todos que receberam uma edição anterior.
• Publicações de notícias só está disponível para agendamentos de Newsletter; os agendamentos RSS mantêm sua própria lógica de feed.

• A lista de agendamentos rotula estes agendamentos como “Publicações de notícias” em vez de “Newsletter”.
• O painel de detalhes mostra quantas publicações Prontas esperam por este agendamento.
• No formulário, modelos sem {{news_posts}} são sinalizados, e um aviso aparece se você escolher um.

O MarbleSend desacopla a execução das campanhas dos relays de entrega por meio de dois modelos de transporte: (1) Bring Your Own (BYO) SMTP para conectar seus servidores de e-mail existentes, e (2) MarbleSend SMTP via Amazon SES para entrega corporativa em nuvem sem configurar contas AWS nem aquecer IPs. Campanhas vinculam-se dinamicamente com fallback padrão transparente e contabilidade atômica.

# Check resolution via dig (macOS / Linux):
dig CNAME <token1>._domainkey.yourdomain.com +short

# Check resolution via nslookup (Windows / PowerShell):
nslookup -type=CNAME <token1>._domainkey.yourdomain.com

O MarbleSend envia e-mails em segundo plano. Uma cron job é um temporizador no painel da sua hospedagem que acorda o MarbleSend a cada minuto para que ele possa executar agendamentos e autoresponders, repetir envios falhados, recolher bounces e manter uma Campaign longa em andamento. Uma Campaign que enviar começa de imediato, mas tudo o que tem de acontecer mais tarde depende deste temporizador. Se Settings → Sistema mostrar Cron Não Detectado, o temporizador não existe, não corre a cada minuto ou aponta para o sítio errado. Os três passos abaixo resolvem isso.

Para utilizadores técnicos

A compilação de e-mails, resolução de destinatários, envio e acionamento de webhooks operam de forma assíncrona através de um worker em segundo plano de 1 minuto. MarbleSend utiliza uma arquitetura de ponto de entrada duplo (worker.php CLI nativo ou cron.php HTTP), protegida por bloqueios de file não-bloqueantes.

* * * * * php /home/USER/your-folder/worker.php >/dev/null 2>&1

GET https://your-domain.com/cron.php?token=SECURE_TOKEN

MarbleSend foi concebido como uma plataforma auto-hospedada acessível globalmente. Inclui 23 dicionários nativos com curadoria humana, espelhamento automático de layout RTL para árabe, personalização de tema persistente e segurança rigorosa de utilizador único.

A REST API permite que websites externos, páginas de captura, aplicações móveis e o plugin oficial MarbleSend Forms interajam com segurança com a sua base de dados de contactos e motor de envio. As chaves de API utilizam prefixos criptográficos, armazenamento SHA-256 unilateral e escopos granulares.

Os webhooks fornecem streaming de eventos HTTP em tempo real para endpoints externos, permitindo que CRMs, notificações do Slack ou automações personalizadas reajam imediatamente a novos subscritores, envios de Campaigns, cancelamentos e bounces.

A entregabilidade determina se as suas mensagens chegam à caixa de entrada ou à pasta de spam. MarbleSend possui um motor de inspeção DNS nativo que executa consultas sequenciais não-bloqueantes diretamente a servidores de nomes autoritativos sem APIs de terceiros.

O MarbleSend fornece um motor de IA de modo duplo flexível para redação, sugestão de assuntos e auditoria de spam: (1) Bring Your Own Key (BYOK) para conectar diretamente aos principais LLMs sem sobretaxas, e (2) Créditos de IA MarbleSend para acesso pré-pago a modelos selecionados de alta qualidade sem gerenciar chaves de API.

MarbleSend verifica a autenticidade do produto usando criptografia assimétrica Ed25519 através da extensão nativa libsodium do PHP. Um License Grant Token assinado é emitido na ativação inicial e validado localmente sem necessidade de conexão persistente.

O plugin chama a REST API do MarbleSend por HTTPS, então o WordPress e o MarbleSend podem rodar em servidores diferentes. Ele não tem acesso ao banco de dados do MarbleSend.

curl -X POST https://your-domain.com/api/contacts \
  -H "Authorization: Bearer ms_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"email":"visitor@example.com","name":"John Doe","tags":["newsletter","source:wpforms"]}'

Um MarbleSend lento ou inacessível não deve travar o formulário de um visitante nem perder um lead. Os envios dos plugins de formulário entram em fila e são enviados em segundo plano.

// Non-blocking submission buffer in WordPress
set_transient('marblesend_forms_queue_' . wp_generate_uuid4(), $payload, 3600);
if (!wp_next_scheduled('marblesend_forms_process_queue')) {
    wp_schedule_single_event(time() + 5, 'marblesend_forms_process_queue');
}

O plugin inclui um formulário de inscrição, então você não precisa de um construtor de formulários. Adicione-o com um shortcode, um bloco do Gutenberg ou um widget. Os três rodam o mesmo código.

[marblesend_form tags="newsletter,inbound" show_name="1" consent="I agree to receive email updates and accept the privacy policy."]

O WPForms é um dos construtores de formulário mais usados. O plugin lê o envio depois que o WPForms o valida, então você não precisa de nenhum complemento do WPForms.

add_action('wpforms_process_complete', function($fields, $entry, $form_data, $entry_id) {
    $email = $fields[1]['value'] ?? ''; // Numeric Field ID #1
    $name  = $fields[0]['value'] ?? ''; // Numeric Field ID #0
    MarbleSend_Integration_Base::dispatch('wpforms', $form_data['id'], $email, $name);
}, 10, 4);

O Contact Form 7 define seus campos como tags em um modelo de texto. O plugin entra depois que o email do formulário foi enviado.

add_action('wpcf7_mail_sent', function($contact_form) {
    $submission = WPCF7_Submission::get_instance();
    $data = $submission ? $submission->get_posted_data() : [];
    $email = $data['your-email'] ?? '';
    $name  = $data['your-name'] ?? '';
    MarbleSend_Integration_Base::dispatch('cf7', $contact_form->id(), $email, $name);
}, 10, 1);

O plugin escuta a ação que o Fluent Forms dispara depois de salvar uma entrada.

add_action('fluentform/submission_inserted', function($entryId, $formData, $form) {
    $email = $formData['email'] ?? '';
    $name  = is_array($formData['names'] ?? null) ? implode(' ', $formData['names']) : ($formData['first_name'] ?? '');
    MarbleSend_Integration_Base::dispatch('fluentforms', $form->id, $email, $name);
}, 10, 3);

O plugin lê a entrada logo depois que o Formidable Forms a salva.

add_action('frm_after_create_entry', function($entryId, $formId) {
    $entry = FrmEntry::getOne($entryId, true);
    $email = $entry->metas[12] ?? $entry->metas['email-address'] ?? '';
    $name  = $entry->metas[11] ?? $entry->metas['full-name'] ?? '';
    MarbleSend_Integration_Base::dispatch('formidable', $formId, $email, $name);
}, 30, 2);

O plugin escuta o hook que o Forminator dispara enquanto processa um envio.

add_action('forminator_custom_form_submit_before_set_fields', function($formId, $response, $fieldData) {
    $fields = array_column($fieldData, 'value', 'name');
    $email  = $fields['email-1'] ?? '';
    $name   = $fields['name-1'] ?? '';
    MarbleSend_Integration_Base::dispatch('forminator', $formId, $email, $name);
}, 10, 3);

Capturar um email é só o primeiro passo. As tags decidem o que acontece com o contato depois.

{
  "email": "lead@agency.com",
  "name": "Jane Smith",
  "tags": ["source:wpforms", "ebook-download", "vip-inbound"],
  "consent_source": "api"
}