Chamar sistema de email via PHP

Objetivo do tutorial

Nota: Este tutorial é direcionado a desenvolvedores e mostra como o sistema de e-mail integrado do bluetronix CMS pode ser acessado diretamente através do PHP.

O bluetronix CMS oferece funções PHP centrais para o envio de e-mails.

Assim, conexões SMTP, contas de e-mail e funções básicas de envio não precisam ser programadas novamente para cada script PHP individual.

A seguinte função está disponível para o envio direto de e-mails e newsletters:

BlueSMTPMail($MailType,$MailAccount,$SMTPType,$From,$To,$NewsletterTo,$Subject,$TextContent,$HTMLContent,$Attachments,$EmbedImages,$MailPlaceholderReplacement,$FormEntry);

Para o envio de e-mails de formulário, a seguinte função adicional está disponível:

BlueFormSend($SMTPType,$SendMail,$SendSubject,$CopyToCustomer,$TextToCustomer,$FormArchive,$FormID,$SendTo);

BlueSMTPMail()

Com BlueSMTPMail(), e-mails normais e newsletters podem ser enviados através do sistema de e-mail central do bluetronix CMS.

A chamada da função é:

BlueSMTPMail(
   $MailType,
   $MailAccount,
   $SMTPType,
   $From,
   $To,
   $NewsletterTo,
   $Subject,
   $TextContent,
   $HTMLContent,
   $Attachments,
   $EmbedImages,
   $MailPlaceholderReplacement,
   $FormEntry
);

$MailType

Determina que tipo de e-mail deve ser enviado.

Valores possíveis:

Mail
Newsletter

Exemplo:

$MailType = "Mail";

ou:

$MailType = "Newsletter";

$MailAccount

$MailAccount determina a conta de e-mail cujas configurações SMTP devem ser usadas.

Esse valor carrega os dados de configuração SMTP correspondentes das tabelas do banco de dados do CMS.

Qual configuração é utilizada depende também de $SMTPType.

$SMTPType

Determina se uma conta de e-mail interna ou externa será utilizada.

Valores possíveis:

Intern
Extern

Interna

Em:

$SMTPType = "Intern";

uma conta de e-mail que foi configurada diretamente no bluetronix CMS será utilizada.

As contas podem ser encontradas em:

Email → Accounts

O endereço de e-mail do remetente utilizado em $From deve estar presente lá como uma conta.

Externa

Em:

$SMTPType = "Extern";

serão utilizados dados de acesso SMTP externos.

Esses dados são gerenciados no CMS em:

Email → Server - Extern

.

O endereço de e-mail do remetente utilizado em $From deve estar configurado adequadamente lá.

$From

Contém o endereço de e-mail do remetente.

Exemplo:

$From = "info@example.com";

O endereço de e-mail deve corresponder à configuração SMTP escolhida.

$To

Contém o endereço de e-mail do destinatário de um e-mail normal.

Exemplo:

$To = "customer@example.com";

Em um envio de e-mail normal, esta variável é usada como destinatário.

$NewsletterTo

$NewsletterTo é usado no envio de newsletters.

A variável contém vários endereços de e-mail como texto. Cada endereço de e-mail é separado por uma quebra de linha.

Exemplo:

$NewsletterTo = "customer1@example.com\ncustomer2@example.com\ncustomer3@example.com";

$Subject

Contém o assunto do e-mail.

Exemplo:

$Subject = "Welcome to our website";

$TextContent

Contém a parte de texto puro do e-mail.

Esta parte pode ser utilizada, por exemplo, por programas de e-mail que não exibem e-mails em HTML.

Exemplo:

$TextContent = "Thank you for your request.";

$HTMLContent

Contém a parte HTML do e-mail.

Exemplo:

$HTMLContent = "<h1>Thank you</h1><p>Thank you for your request.</p>";

Com isso, e-mails formatados com cabeçalhos, textos, links, imagens e outros elementos HTML podem ser enviados.

$Attachments

Com $Attachments, é possível anexar arquivos ao e-mail.

Os arquivos são especificados pelo seu caminho dentro do site.

Exemplo:

$Attachments = "/bx_doc/Intro.pdf";

Em caso de múltiplos anexos, os caminhos individuais dos arquivos são separados por uma quebra de linha.

Exemplo:

$Attachments = "/bx_doc/Intro.pdf\n/bx_doc/PriceList.pdf";

$EmbedImages

Com $EmbedImages, pode-se definir se as imagens devem ser incorporadas diretamente no e-mail.

Exemplo:

$EmbedImages = "ja";

Com a opção ativada, as imagens utilizadas dentro do e-mail HTML são integradas diretamente no e-mail e não apenas carregadas por meio de URLs externas.

Dessa forma, as imagens podem estar disponíveis diretamente no e-mail para o destinatário, sem necessidade de serem carregadas separadamente do servidor web.

$MailPlaceholderReplacement

Com $MailPlaceholderReplacement, podem-se substituir marcadores dentro de:

$TextContent
$HTMLContent

por valores individuais.

O princípio é:

Search
   ↓
Replace

Dessa forma, por exemplo, conteúdos personalizados podem ser gerados dentro de um e-mail.

As aplicações típicas são:

• Name des Empfängers
• Kundennummer
• Bestellnummer
• individuelle Links
• weitere dynamische Inhalte

$FormEntry

Com $FormEntry, pode-se definir se o envio deve ser salvo adicionalmente no arquivo de formulários.

Em:

$FormEntry = "JA";

é adicionado um registro na tabela do banco de dados:

00_form

salvo.

Assim, o envio pode ser documentado simultaneamente como uma entrada de formulário ou arquivo.

Exemplo: Enviar e-mail normal

O seguinte exemplo envia um e-mail normal em HTML e texto através de uma conta interna.

$MailType                  = "Mail";
$MailAccount               = "info@example.com";
$SMTPType                  = "Intern";
$From                      = "info@example.com";
$To                        = "customer@example.com";
$NewsletterTo              = "";
$Subject                   = "Your request";
$TextContent               = "Thank you for your request.";
$HTMLContent               = "<h1>Thank you</h1><p>Thank you for your request.</p>";
$Attachments               = "/bx_doc/Intro.pdf";
$EmbedImages               = "ja";
$MailPlaceholderReplacement = "";
$FormEntry                 = "NEIN";

BlueSMTPMail($MailType,$MailAccount,$SMTPType,$From,$To,$NewsletterTo,$Subject,$TextContent,$HTMLContent,$Attachments,$EmbedImages,$MailPlaceholderReplacement,$FormEntry);

O processo é simplificado da seguinte forma:

PHP
   ↓
BlueSMTPMail()
   ↓
internen Mail-Account laden
   ↓
SMTP-Verbindung verwenden
   ↓
E-Mail erzeugen
   ↓
E-Mail versenden
   ↓
MailCache-Eintrag erzeugen

Exemplo: Enviar newsletter

Para um boletim informativo, $MailType é definido como:

Newsletter

definido.

Os destinatários são então passados por $NewsletterTo.

$MailType                  = "Newsletter";
$MailAccount               = "newsletter@example.com";
$SMTPType                  = "Intern";
$From                      = "newsletter@example.com";
$To                        = "";
$NewsletterTo              = "customer1@example.com\ncustomer2@example.com\ncustomer3@example.com";
$Subject                   = "Our latest news";
$TextContent               = "Discover our latest news and products.";
$HTMLContent               = "<h1>Our latest news</h1><p>Discover our latest news and products.</p>";
$Attachments               = "";
$EmbedImages               = "ja";
$MailPlaceholderReplacement = "";
$FormEntry                 = "NEIN";

BlueSMTPMail($MailType,$MailAccount,$SMTPType,$From,$To,$NewsletterTo,$Subject,$TextContent,$HTMLContent,$Attachments,$EmbedImages,$MailPlaceholderReplacement,$FormEntry);

Os destinatários individuais do boletim informativo são separados por quebras de linha dentro de $NewsletterTo.

Usar conexão SMTP externa

Se um servidor de email externo deve ser usado, é necessário:

$SMTPType = "Extern";

definido.

Os dados de acesso SMTP devem ser configurados previamente em:

Email → Server - Extern

devem ter sido configurados.

Exemplo:

$SMTPType    = "Extern";
$From        = "mail@external-domain.com";
$MailAccount = "mail@external-domain.com";

BlueFormSend()

Além do envio direto de e-mails, a função:

BlueFormSend($SMTPType,$SendMail,$SendSubject,$CopyToCustomer,$TextToCustomer,$FormArchive,$FormID,$SendTo);

está disponível.

Esta função é especificamente destinada ao envio de e-mails em conjunto com formulários CMS.

As variáveis já estão completamente em inglês.

Parâmetros de BlueFormSend()

MailCache

Cada chamada de BlueSMTPMail() gera também uma entrada na tabela do banco de dados:

00_MailCache

Através dessa tabela, pode-se controlar o status do envio do e-mail.

Lá, por exemplo, pode-se verificar se um e-mail foi processado ou enviado com sucesso.

As entradas do MailCache são para:

1 Woche

salvo.

Fluxo típico de um envio de e-mail

PHP-Skript
   ↓
BlueSMTPMail()
   ↓
MailType prüfen
   ↓
MailAccount auswählen
   ↓
SMTPType prüfen
   ↓
SMTP-Konfiguration laden
   ↓
Empfänger bestimmen
   ↓
Text- und HTML-Inhalt erstellen
   ↓
Platzhalter ersetzen
   ↓
Anhänge hinzufügen
   ↓
Bilder gegebenenfalls einbetten
   ↓
E-Mail versenden
   ↓
00_MailCache aktualisieren
   ↓
optional 00_form speichern

Visão geral dos parâmetros de BlueSMTPMail

Zusammenfassung

O sistema de e-mail central do CMS bluetronix pode ser chamado diretamente a partir do próprio código PHP.

Für normalen E-Mail- und Newsletter-Versand wird verwendet:

BlueSMTPMail($MailType,$MailAccount,$SMTPType,$From,$To,$NewsletterTo,$Subject,$TextContent,$HTMLContent,$Attachments,$EmbedImages,$MailPlaceholderReplacement,$FormEntry);

Para formulários do CMS, está disponível adicionalmente:

BlueFormSend($SMTPType,$SendMail,$SendSubject,$CopyToCustomer,$TextToCustomer,$FormArchive,$FormID,$SendTo);

Die SMTP-Konfiguration kann entweder über:

Interno
→ Email → Contas

ou:

Extern
→ Email → Server - Extern

erfolgen.

Cada envio de e-mail é também registrado em:

00_MailCache

protokolliert. Die entsprechenden Cache-Einträge bleiben eine Woche erhalten.

Assim, os desenvolvedores podem usar o sistema de e-mail já existente do CMS bluetronix diretamente de seus próprios scripts PHP, sem precisar implementar toda a lógica SMTP.