PHP Mail

config/_init.php

$GLOBALS['domain_emailmode']=0; //0=mail by server, 1=PHPMailer $GLOBALS['domain_emailrights']=3; // 0:no emails, // 1:to logged in user only, // 2:logged in to every one, // 3: role: 32 $GLOBALS['domain_testemail']="<this email can be used several times>"; $GLOBALS['domain_email']=array( "activate"=>array( // activation email "subject"=>"activate your account", "content"=>"Dear member,<br>please activate your account: <a href=\"{{activation_link}}\">activation link</a><br>Greetings<br>{{domain_name}}" ), "sendPwd"=>array( // send password "subject"=>"new password", "content"=>"Dear member,<br>your new password: {{password}}<br>Greetings<br>{{domain_name}}" ), "template"=>array( "subject"=>"template", "content"=>"Dear member,<br>{{content}}<br>Greetings<br>{{domain_name}}" ) );

The default domain_emailmode is set to "1: email by PHPmailer". Please fill out your email configuration in the _init.php.

If the domain_emailmode is set to "0: email by server": please look to your Server Email Configuration and check the configuration.

The default domain_testemail can be used for several user as test. Please regard that "Send Password" is not working well in this case.

domain_email allows to configure:

• activate, Activation email
• sendPwd, Send password email

For both:

• subject
• content

can be declared. The content supports HTML-emails.

The template can be used for further necessary emails.

config/_init.php

$GLOBALS['domain_PHPMailer']=array( "from"=>"<email address>", // sender email address "fromname"=>"Jane Doe", // sender name "host"=>"smtp.gmail.com", // Outgoing mail server (SMTP) "SMTPAuth"=>true, // SMTP Authentication activated "username"=>"<email address>", // SMTP username "password"=>"<password>", // SMTP password "SMTPSecure"=>"ssl", // 'ssl' or 'tls' (465 or 587) "port"=>465 // Port of Outgoing mail server (SMTP) );

The default domain_emailmode is set to "1: PHPMailer". Please continue with the configuration for your email server. For example for a google email server it is important to configure an App-Password for third party access (description of App Password configuration).

More information to:

• PHPMailer

<projectpath>/_init.json

"domain_PHPMailer":{ "from":"<email address>", "fromname":"Jane Doe", "host":"smtp.gmail.com", "SMTPAuth":true, "username":"<email address>", "password":"<password>", "SMTPSecure":"ssl", "port":465 }

This is the same definitiion written in JSON format.

// configure email let dat_email={}; dat_email['to']="eisert.klaus@gmail.com"; dat_email['subject']="Test"; dat_email['content']="This is a test email." dat_email['url']=GLOBALS_hostpath+'masterdata/ProcessMethod.php?process_action=sendEmail'; // action postData(dat_email['url'],dat_email).then((oJson) => { if(oJson.bok){ k8.message(getl('send!'),'saved'); console.log("send"); }else{ k8.message(getl("not send: ")+oJson.error,'alert'); console.log("not send: "+oJson.error); } }).catch(function (err) { k8.message(err,'alert'); console.warn('fetch error ', err); });

domain_emailrights

• 0: no emails
• 1: to logged in user only (default)
• 2: logged in to every one
• 3: role: 32
• 4: own email configuration (future)

Parameters:

• to
• cc
• bcc
• subject
• message: this is the whole email body
• content: uses the template

$to="<recipients email>"; $dat=array( "cc"=>"emails, separated by komma, for copy", "bcc"=>"emails, separated by komma, for blind copy", "subject"=>"<your subject>", "content"=>"<your content> (template is used)", "message"=>"or <your message>", "PHPMailer"=>array( // customer email access data "from"=>"<email address>", // sender email address ... ) ); $email=new eMailbyPHPMailer($to,$dat); $file="<your file with path>"; if($email->bprepareAttachment($file,1)){ if($email->bsend()){ return 1; }else{ $this->error=$email->getError(); return 0; } }else{ $this->error=$email->getError(); return 0; }

If you want to use PHPMailer for own emails even by your customer, you can declare PHPMailer like this and transfer the customer mail server access data.

// the .ics file, see "Create an ICS file" let ics=buildIcs(dat_form,60); let dat_email={}; dat_email['to']="<recipient email>"; dat_email['template']="activity_ics"; // email template: k8emailtemplates.action dat_email['placeholder']={ // replaces {{subject}}, {{activitydate}} ... subject:dat_form['subject'], activitydate:"03.09.2026, 13:09" }; dat_email['attachments']=[{name:"termin.ics",content:ics}]; dat_email['url']=GLOBALS_hostpath+'masterdata/ProcessMethod.php?process_action=sendEmail'; // action postData(dat_email['url'],dat_email).then((oJson) => { if(oJson.bok){ k8.message(getl('send!'),'saved'); }else{ k8.message(getl("not send: ")+oJson.error,'alert'); } }).catch(function (err) { k8.message(err,'alert'); console.warn('fetch error ', err); });

Additional parameters of sendEmail:

• template: the action of an email template in k8emailtemplates. It delivers the subject and the message, if you don't send them.
• placeholder: replaces {{subject}}, {{activitydate}} ... in the subject and in the message.
• attachments: a list of name and content.

The browser may only send calendar files:

• the name ends with .ics
• the content starts with BEGIN:VCALENDAR
• max. 3 files, each max. 100 KB

Otherwise the email is not sent: "attachment not allowed (only .ics)". An unknown template returns "email template not found". Who may send emails is defined by domain_emailrights.

Example: the menu "Send ics" of the datadefinition addressactivities, the template is activity_ics.

$to="<recipients email>"; $dat=array( "subject"=>"<your subject>", "message"=>"<your message>" ); $email=new eMailbyPHPMailer($to,$dat); // a file on the server; 1 = temporary file, it is deleted after sending $file="<your file with path>"; $email->bprepareAttachment($file,1); // or a file from a string, there is no file on the server $ics="BEGIN:VCALENDAR ..."; $email->bprepareStringAttachment("termin.ics",$ics,"text/calendar; charset=utf-8"); if($email->bsend()){ return 1; }else{ $this->error=$email->getError(); return 0; }

Both email classes, eMailbyPHPMailer and eMailbyServer, can attach files.

• bprepareAttachment($file,$temporary): attaches a file of the server. With $temporary=1 it is deleted after sending.
• bprepareStringAttachment($name,$content,$type): attaches a content without a file, e.g. a calendar file you have just created.

Call the methods before bsend(). If something fails, getError() returns the reason.

BEGIN:VCALENDAR VERSION:2.0 PRODID:-//K8 Web Kit//addressactivities//EN METHOD:PUBLISH BEGIN:VEVENT UID:61@localhost ATTENDEE;CUTYPE=INDIVIDUAL;ROLE=REQ-PARTICIPANT;RSVP=TRUE:mailto:max@example.com LOCATION: SUMMARY:Meeting Q4 DESCRIPTION:Agenda follows.\nPlease bring the documents. CLASS:PUBLIC DTSTART:20260903T130900 DTEND:20260903T143900 DTSTAMP:20261007T222604 END:VEVENT END:VCALENDAR

An ICS file is a text file with the lines KEY:value.

• BEGIN:VCALENDAR ... END:VCALENDAR: the whole calendar file
• VERSION, PRODID: version of the format and the program, which created the file
• METHOD:PUBLISH: the recipient can add the appointment to the calendar. To let the recipient accept or decline, use METHOD:REQUEST and an ORGANIZER.
• BEGIN:VEVENT ... END:VEVENT: one appointment
• UID: unique ID of the appointment (record ID and host)
• ATTENDEE: the participant, with mailto:
• LOCATION, SUMMARY (title), DESCRIPTION (text), CLASS
• DTSTART, DTEND: begin and end as YYYYMMDDTHHMMSS (local time)
• DTSTAMP: time of creation

Rules:

• the lines are separated by CRLF
• a long line is folded: the next line begins with a blank
• in texts the characters , ; \ and a line break are written as \, \; \\ and \n

function buildIcs(dat,minutes){ const pad=(n)=>String(n).padStart(2,'0'); const fmt=(d)=>d.getFullYear()+pad(d.getMonth()+1)+pad(d.getDate())+'T'+pad(d.getHours())+pad(d.getMinutes())+pad(d.getSeconds()); const esc=(s)=>String(s||'').replace(/\\/g,'\\\\').replace(/;/g,'\\;').replace(/,/g,'\\,').replace(/\r?\n/g,'\\n'); const fold=(line)=>line.replace(/(.{60})(?=.)/g,'$1\r\n '); let start=new Date(dat['activitydate']); if(isNaN(start))start=new Date(); let end=new Date(start.getTime()+minutes*60000); let el=document.createElement('div'); el.innerHTML=String(dat['description']||'').replace(/<br\s*\/?>|<\/p>/gi,'\n'); let lines=[ 'BEGIN:VCALENDAR', 'VERSION:2.0', 'PRODID:-//K8 Web Kit//addressactivities//EN', 'METHOD:PUBLISH', 'BEGIN:VEVENT', 'UID:'+dat['activityID']+'@'+location.hostname, 'ATTENDEE;CUTYPE=INDIVIDUAL;ROLE=REQ-PARTICIPANT;RSVP=TRUE:mailto:'+dat['email'], 'LOCATION:', 'SUMMARY:'+esc(dat['subject']), 'DESCRIPTION:'+esc(el.textContent.trim()), 'CLASS:PUBLIC', 'DTSTART:'+fmt(start), 'DTEND:'+fmt(end), 'DTSTAMP:'+fmt(new Date()), 'END:VEVENT', 'END:VCALENDAR' ]; return lines.map(fold).join('\r\n')+'\r\n'; }

The function builds the text of the ICS file from a record. It is used by "Send ics" in addressactivities_head_end.js.

• dat: the record (activityID, subject, description, email, activitydate)
• minutes: duration of the appointment. The end is the begin plus the minutes.
• fmt: formats a date as YYYYMMDDTHHMMSS
• esc: masks the special characters of a text
• fold: folds lines longer than 60 characters
• The HTML of the description is converted to text, a paragraph and a <br> become a line break.
• The lines are joined with CRLF, the last line ends with CRLF too.

The result is attached to the email as termin.ics, see "Email with attachment".

# Save: the recipient adds the appointment to the calendar (METHOD:PUBLISH) # this is what "Send ics" sends BEGIN:VCALENDAR VERSION:2.0 PRODID:-//K8 Web Kit//addressactivities//EN METHOD:PUBLISH BEGIN:VEVENT UID:61@localhost ATTENDEE;CUTYPE=INDIVIDUAL;ROLE=REQ-PARTICIPANT;RSVP=TRUE:mailto:max@example.com SUMMARY:Meeting Q4 DTSTART:20261015T100000 DTEND:20261015T110000 DTSTAMP:20261008T071500 END:VEVENT END:VCALENDAR # Invite: the recipient can accept or decline (METHOD:REQUEST) # changed or new lines are marked with <-- BEGIN:VCALENDAR VERSION:2.0 PRODID:-//K8 Web Kit//addressactivities//EN METHOD:REQUEST <-- BEGIN:VEVENT UID:61@localhost ORGANIZER;CN=Klaus Eisert:mailto:organizer@example.com <-- ATTENDEE;CN=Max;PARTSTAT=NEEDS-ACTION;RSVP=TRUE:mailto:max@example.com SEQUENCE:0 <-- STATUS:CONFIRMED <-- SUMMARY:Meeting Q4 DTSTART:20261015T100000 DTEND:20261015T110000 DTSTAMP:20261008T071500 END:VEVENT END:VCALENDAR

Currently "Send ics" sends a publication (METHOD:PUBLISH). An invitation (METHOD:REQUEST) needs only a few more lines, but the recipient gets Accept / Tentative / Decline buttons directly in the email.

• METHOD:REQUEST instead of PUBLISH
• ORGANIZER (required): the sender with a valid email address. The answers of the recipients go to this address.
• SEQUENCE: counts the changes. Send the same UID with a higher SEQUENCE to update the appointment.
• STATUS:CONFIRMED: the appointment is fixed. To cancel it send the same UID with METHOD:CANCEL.

The content type of the attachment must contain the method, otherwise Outlook and Gmail do not show the buttons:

text/calendar; method=REQUEST; charset=utf-8

It is the third parameter of bprepareStringAttachment(), see "Email with attachment".

Email templates allow you to conveniently create and format templates.

Action

The name for the email, should be the action, which it's used for. The system emails use the actions (see System emails):

• activate
• resetPwd
• inviteUser
• activateReminder
• mfaCode

Language

You can define different languages for one action.

Bcc

if necessary send the email to blind copy.

Content

The Content can be formated with this editor (tinymce). Placeholders can be used like this {{placeholder}}. By sending the email, they are exchanged for the value of the data record. The content is inserted in the global email template.

Message

The message is equivalent to the content. This message is send as email body. It should have also a signature.

Images

Images can be uploaded by the image icon, "Upload". The image can be resized by the image handler. It's saved in the upload folder and the complete url is linked in the image tag.

The ediors above use absolut path with (datadefinition.masterdata.seofriendly: true).

The function gbSystemEmail() (masterdata/BasicFunctions.php) sends the emails of the user management. Each email contains a link with a one-time token (table k8logintoken). The token can be used once and expires.

Actions

Action	Sent when	Link	Valid (config/_init.php)	Placeholders
activate	after the registration (process_action sendActivation), the user must activate the account	{{activation_link}}, page activate	expiration_activation, hours (default 144)	{{activation_link}}, {{expires}}, {{domain_name}} and the fields of the user
resetPwd	password forgotten (process_action passwordreset_email), the user sets a new password	{{reset_link}}, page passwordreset	expiration_pwdreset, minutes (default 1440)	{{reset_link}}, {{expires}}, {{domain_name}} and the fields of the user
inviteUser	administrator or superuser invites a user (menu "Invite user" in the user list, process_action userinvite_email), the user sets the password	{{reset_link}}, page passwordreset	expiration_pwdinvite, minutes (default 10080 = 7 days)	{{username}}, {{reset_link}}, {{expires}}, {{domain_name}} and the fields of the user
activateReminder	reminder for a not activated user, sent by the cron job masterdata/k8activationreminder.php after activation_reminder_hours (see User management)	{{activation_link}}, page activate	activation_delete_hours, hours (default 72), then the user is deleted	{{activation_link}}, {{expires}}, {{domain_name}} and the fields of the user
mfaCode	login with e-mail code (domain_mfa), after the correct password; sent by k8MfaStart(), not by gbSystemEmail()	no link, 6-digit code	domain_mfa['minutes'] (default 10)	{{code}}, {{minutes}}, {{username}}, {{domain_name}}

Placeholders

• {{expires}}: date and time until the link is valid, format dd.mm.yyyy hh:mm (time of the database server).
• {{domain_name}}: the name of the website (domain_name in config/_init.php).
• The fields of the user are the columns of the table k8login, e.g. {{username}}, {{email}}, {{firstname}}, {{lastname}}.

Which text is used

1. The template with this action in the table k8emailtemplates. The language is searched in this order: the language of the user, the system language (domain_langnative), any language. The language is the value (en, de, ...) of the group chosen in languageID. Subject and message come from the template.
2. No template: the default text in $GLOBALS['domain_email'][action] (config/_init.php, keys subject and content). For the activation the texts of the registration form (email_subject, email_content) are used first.

The subject is converted to plain text before sending (tags removed, entities like &nbsp; resolved).

sendPwd (new password in the email) is switched off, because it stored the password as plain text. The action is still in $GLOBALS['domain_email'], use resetPwd instead.

Your datadefintion :

{ "head_include": [ "{{projectpath}}/{{datadefID}}/{{datadefID}}_head_include.php" ], }

The file: {{datadefID}}_head_include.php is included. This includes the email templates into your web site.

the include for php:

<script> <?php $data_emailtemplates=array(); $clause=""; $mydatadefID='k8emailtemplates';$error=''; $o_emailtemplates=getDatadefinition($mydatadefID,$error,"",0,"",1,false,-1); if($o_emailtemplates->getentries($clause))$data_emailtemplates=$o_emailtemplates->data; $bdefault=true; echo 'var data_emailtemplates='.json_encode($data_emailtemplates); ?> </script>

The variable data_emailtemplates is declared in JavaScript. It's an array with all defined templates.

JavaScript excerp of callback cbmenuleft of reclamationapprovals:

// dat: object reclamationapprovals // dat_emailtemplate: object emailtemplates // dat_reclamations: object reclamations // dat_email: object for the email, which is send dat['statustext']=""; if(Number(dat.status)==0){ dat['statustext']=getl('Your reclamation is pending.'); }else if(Number(dat.status)==1){ dat['statustext']=getl('Your reclamation is approved.'); }else if(Number(dat.status)==2){ dat['statustext']=getl('Your reclamation is rejected.'); } let dat_emailtemplate = data_emailtemplates.find(col => col.action === "reclamation_approval"); if(!dat_emailtemplate){ k8.message("email template: reclamation_approval is not defined",'alert'); return; } let dat_email={}; dat_email['to']=dat_reclamations.email; dat_email['bcc']=dat_emailtemplate['bcc']; dat['title']=dat_reclamations.title; dat_email['subject']=ReplacePlaceholder(dat_emailtemplate.subject,dat,2); dat_email['message']=ReplacePlaceholder(dat_emailtemplate.message,dat,2); dat_email['url']=GLOBALS_hostpath+'masterdata/ProcessMethod.php?process_action=sendEmail'; // action postData(dat_email['url'],dat_email).then((oJson) => { if(oJson.bok){ k8.message(getl('send!'),'saved'); row_actual.update({'emailsend':true}); // save url=GLOBALS_hostpath+settings.masterdata.url_save; dat={'approvalID':dat.approvalID,'emailsend':1}; postData(url,dat).then((obj) => { //console.log(obj); if(obj.bok){ //k8.message(getl('Saved'),'saved'); }else{ k8.message(obj.error,'alert'); } }); }else{ k8.message(getl("not send: ")+oJson.error,'alert'); //console.log("not send: "+oJson.error); } }).catch(function (err) { k8.message(err,'alert'); console.warn('fetch error ', err); });

Process

• statustext: prepare the status text
• dat_emailtemplates: filter the template reclamation_approval from array
• prepare the data for the email, dat_email:
  • to
  • bcc
  • subject
  • message
• command PHP to send the email
• set emailsend in the recclamationapprovals
• set recclamationapprovals

The datadefinition k8emailconfig allows you to define additional email connectors.

Some email provider use a Two-factor authentication (2FA). The version of PHP Mailer used by K8 Web Kit don't support 2FA. Other programs don't do that either. For this reason many email provider, like google, microsoft or yahoo allow to configure an app password. So you simply enter the app password here.

This email configuration is joined to the company object. It can be joined to your objects. It can be called by:

• ProcessMethod.php
  • process_action=sendUserEmail
    • configID=<your ID>
    • ... like above