Blesta Source Documentation

Emails extends AppModel

Email management

Table of Contents

Properties

$default_tags An array of key/value pairs to be used as default tags for email templates

Methods

__construct() Initialize Emails
add() Adds an email with the given data
addAttachments() Adds one or more attachments to an existing email template
addSignature() Adds the given signature to the system
buildEmail() Parses an Email stdClass object using the given data ($tags)
delete() Permanently removes the email from the system.
deleteAll() Permanently removes all email templates of the given group from the system.
deleteAttachment() Deletes one or more attachments from an existing email template
deleteSignature() Permanently removes an email signature from the system
edit() Updates the email with the given data
editSignature() Updates an existing signature in the system
get() Retrieves a single email template by ID, including email group tags
getAllSignatures() Retrieves a list of all signatures for this company
getAttachment() Fetches an attachment
getAttachments() Fetches all the attachments from an existing email template
getByGroupId() Retrieves a single email template by Group ID for the current company
getByType() Fetches a single email template by company ID, type, and (optionally) language
getGroup() Fetches an email group
getGroupList() Fetches all email groups
getHtmlTemplate() Fetches a single email html template by company ID, type, and (optionally) language
getList() Fetches a list of all email templates under a company for the given email group in every available language
getSignature() Fetches an email signature
getSignatureList() Fetches a list of all email signatures for a given company
getSignatureListCount() Fetches the total number of signatures returned from Emails::getSignatureList(), useful in constructing pagination for the getSignatureList() method.
getStatusTypes() Retrieves a list of email status types
send() Sends the given email using the criteria specified
sendCustom() Sends a custom email using the criteria specified
updateFromDomain() Updates the domani portion of the from name for every email in the given company.
validateAttachmentPaths() Validates that the given attachments exist on the file system
validateEmailAddresses() Validates that each of the given email addresses provided are valid
validateEmailGroupAction() Validates that the given action is a valid email group action
validateParse() Validate that the given string parses template parsing
validateSignatureExists() Validates the email signature submitted exists and belongs to the company ID given
validateSignatureInUse() Checks whether the email signature given is in use by any email
validateStatus() Validates the emails 'status' field
validateUnique() Validates the given company ID, email group ID, and language type are unique for this email
getEmailRules() Returns the rule set for adding/editing emails
getEmails() Constructs a partial Record query used to fetch emails
getSendEmailRules() Returns the rule set for adding/editing emails
getSignatureRules() Returns the rule set for adding/editing signatures
getSignatures() Partially constructs the query required by both Emails::getSignatureList() and Emails::getSignatureListCount()
htmlToText() Converts the given HTML to text if the given text contains no characters
parse() Parses an email and evaluates the tags on provided in the body
sendEmail() Performs the heavy lifting to send the given email and log it.
setFilters() Sets filters on the parser
setParseError() Sets the parse error in the set of errors
Properties

$default_tags

An array of key/value pairs to be used as default tags for email templates

private mixed $default_tags = []
Methods

__construct()

Initialize Emails

public __construct() : mixed

add()

Adds an email with the given data

public add(array<string|int, mixed> $vars) : int
Parameters
$vars : array<string|int, mixed>

An array of email info including:

  • email_group_id The ID of the group this email belongs to
  • company_id The company ID this email belongs to
  • lang The language in ISO 636-1 2-char + "_" + ISO 3166-1 2-char (e.g. en_us) (optional, default en_us)
  • from The address the message will be sent from
  • from_name The name belonging to the from address
  • subject The subject of the message
  • text The plain-text body of the message (if empty will be created based on the html content) (optional, default null)
  • html The html body of the message (optional, default null)
  • email_signature_id The signature to append to the email (optional, default null)
  • include_attachments 1 to include attachments when the email is sent, 0 to not send attachments with the email (optional, default 1)
  • status The status of this email 'active', 'inactive' (optional, default active)
Return values
int —

The ID of the email, void on error

addAttachments()

Adds one or more attachments to an existing email template

public addAttachments(int $id, array<string|int, mixed> $vars) : mixed
Parameters
$id : int

The ID of the email template

$vars : array<string|int, mixed>

An array of email info including:

  • orig_name The original file name
  • file_name The current file name
  • full_path The full path to the file

addSignature()

Adds the given signature to the system

public addSignature(array<string|int, mixed> $vars) : mixed
Parameters
$vars : array<string|int, mixed>

An array of signature info including:

  • company_id The company ID to create the signature under
  • name The name of the signature
  • text The plaintext signature
  • html The HTML signature

buildEmail()

Parses an Email stdClass object using the given data ($tags)

public buildEmail(string $action, int $company_id, string $lang[, array<string|int, mixed> $tags = null ]) : mixed
Parameters
$action : string

The action that specifies the email group to use

$company_id : int

The company ID to send this email under

$lang : string

The language in ISO 636-1 2-char + "_"

  • ISO 3166-1 2-char (e.g. en_us) to send, if no message found for this language will attempt to send using company's default language
$tags : array<string|int, mixed> = null

An array of replacement tags containing the key/value pairs for the replacements where the key is the tag to replace and the value is the value to replace it with

Return values
mixed —

A stdClass object representing the parsed email template, false if no such template exists

delete()

Permanently removes the email from the system.

public delete(int $id) : mixed
Parameters
$id : int

The ID of the email to delete

deleteAll()

Permanently removes all email templates of the given group from the system.

public deleteAll(int $email_group_id, int $company_id) : mixed
Parameters
$email_group_id : int

The ID of the email group to remove all email template from

$company_id : int

The ID of the company to remove all email templates in this group

deleteAttachment()

Deletes one or more attachments from an existing email template

public deleteAttachment(mixed $id) : mixed
Parameters
$id : mixed

The ID of the email attachment to delete or an array of IDs

deleteSignature()

Permanently removes an email signature from the system

public deleteSignature(int $email_signature_id) : mixed
Parameters
$email_signature_id : int

The ID of the email signature to delete

edit()

Updates the email with the given data

public edit(int $id, array<string|int, mixed> $vars) : mixed
Parameters
$id : int

The ID of the email to update

$vars : array<string|int, mixed>

An array of email info including:

  • email_group_id The ID of the group this email belongs to
  • company_id The company ID this email belongs to
  • lang The language in ISO 636-1 2-char + "_" + ISO 3166-1 2-char (e.g. en_us) (optional, default en_us)
  • from The address the message will be sent from
  • from_name The name belonging to the from address
  • subject The subject of the message
  • text The plain-text body of the message (if empty will be created based on the html content) (optional, default null)
  • html The html body of the message (optional, default null)
  • email_signature_id The signature to append to the email (optional, default null)
  • include_attachments 1 to include attachments when the email is sent, 0 to not send attachments with the email (optional)
  • status The status of this email 'active', 'inactive' (optional, default active)

editSignature()

Updates an existing signature in the system

public editSignature(mixed $email_signature_id, array<string|int, mixed> $vars) : mixed
Parameters
$email_signature_id : mixed

The ID of the signature in the system to update

$vars : array<string|int, mixed>

An array of signature info including:

  • name The name of the signature
  • text The plaintext signature
  • html The HTML signature

get()

Retrieves a single email template by ID, including email group tags

public get(int $id) : mixed
Parameters
$id : int

The ID of the email template to fetch

Return values
mixed —

A stdClass object representing the email template, false if no such template exists

getAllSignatures()

Retrieves a list of all signatures for this company

public getAllSignatures(int $company_id) : array<string|int, mixed>
Parameters
$company_id : int

The company ID whose signatures to fetch

Return values
array<string|int, mixed> —

An array of stdClass objects each representing a signature

getAttachment()

Fetches an attachment

public getAttachment(int $id) : mixed
Parameters
$id : int

The ID of the email attachment

getAttachments()

Fetches all the attachments from an existing email template

public getAttachments(int $id) : mixed
Parameters
$id : int

The ID of the email template

getByGroupId()

Retrieves a single email template by Group ID for the current company

public getByGroupId(int $group_id[, string $lang = null ]) : mixed
Parameters
$group_id : int

The email group ID to use to fetch the email tempalte for the current company

$lang : string = null

The language in ISO 636-1 2-char + "_"

  • ISO 3166-1 2-char (e.g. en_us) (optional, defaults to default language)
Return values
mixed —

A stdClass object representing the email template, false if no such template exists

getByType()

Fetches a single email template by company ID, type, and (optionally) language

public getByType(int $company_id, string $action[, string $lang = null ]) : mixed
Parameters
$company_id : int

The ID of the company to fetch the email for

$action : string

The email group action to fetch

$lang : string = null

The language of template to fetch, defaults to default language

Return values
mixed —

A stdClass object representing the email template, false if no such template exists

getGroup()

Fetches an email group

public getGroup(int $email_group_id) : mixed
Parameters
$email_group_id : int

The email group ID

Return values
mixed —

An array of objects or false if no results.

getGroupList()

Fetches all email groups

public getGroupList([mixed $sortby = 'action' ][, string $order = 'asc' ]) : mixed
Parameters
$sortby : mixed = 'action'
$order : string = 'asc'

The direction to order (asc, desc)

getHtmlTemplate()

Fetches a single email html template by company ID, type, and (optionally) language

public getHtmlTemplate(int $company_id, string $action[, string $lang = null ]) : mixed
Parameters
$company_id : int

The ID of the company to fetch the html template for

$action : string

The email group action to fetch

$lang : string = null

The language of template to fetch, defaults to default language

Return values
mixed —

A stdClass object representing the email html template, false if no such template exists

getList()

Fetches a list of all email templates under a company for the given email group in every available language

public getList(int $company_id, string $email_group_id) : mixed
Parameters
$company_id : int

The company ID to fetch email templates for

$email_group_id : string

The email group ID

Return values
mixed —

An array of objects or false if no results.

getSignature()

Fetches an email signature

public getSignature(int $email_signature_id) : mixed
Parameters
$email_signature_id : int

The email signature ID

Return values
mixed —

An array of objects or false if no results.

getSignatureList()

Fetches a list of all email signatures for a given company

public getSignatureList(int $company_id[, int $page = 1 ][, string $order_by = ['name' => 'ASC'] ]) : array<string|int, mixed>
Parameters
$company_id : int

The company ID whose signatures to fetch

$page : int = 1

The page to return results for (optional, default 1)

$order_by : string = ['name' => 'ASC']

The sort and order conditions (e.g. array('sort_field'=>"ASC"), optional)

Return values
array<string|int, mixed> —

An array of objects or false if no results.

getSignatureListCount()

Fetches the total number of signatures returned from Emails::getSignatureList(), useful in constructing pagination for the getSignatureList() method.

public getSignatureListCount(int $company_id) : int
Parameters
$company_id : int

The company ID whose signatures to fetch

Tags
see
Emails::getList()
Return values
int —

The total number of signatures

getStatusTypes()

Retrieves a list of email status types

public getStatusTypes() : array<string|int, mixed>
Return values
array<string|int, mixed> —

Key=>value pairs of email status types

send()

Sends the given email using the criteria specified

public send(string $action, int $company_id, string $lang, mixed $to[, array<string|int, mixed> $tags = null ][, mixed $cc = null ][, mixed $bcc = null ][, array<string|int, mixed> $attachments = null ][, array<string|int, mixed> $options = null ]) : bool
Parameters
$action : string

The action that specifies the email group to use

$company_id : int

The company ID to send this email under

$lang : string

The language in ISO 636-1 2-char + "_"

  • ISO 3166-1 2-char (e.g. en_us) to send, if no message found for this language will attempt to send using company's default language
$to : mixed

The To address(es) to send to. A string, or an array of email addresses

$tags : array<string|int, mixed> = null

An array of replacement tags containing the key/value pairs for the replacements where the key is the tag to replace and the value is the value to replace it with

$cc : mixed = null

The CC address(es) to send to. A string, or an array of email addresses

$bcc : mixed = null

The BCC address(es) to send to. A string, or an array of email addresses

$attachments : array<string|int, mixed> = null

A multi-dimensional array of attachments containing:

  • path The path to the attachment on the file system
  • name The name of the attachment (optional, default '')
  • encoding The file encoding (optional, default 'base64')
  • type The type of attachment (optional, default 'application/octet-stream')
$options : array<string|int, mixed> = null

An array of options including:

  • to_client_id The ID of the client the message was sent to
  • from_staff_id The ID of the staff member the message was sent from
  • from The from address
  • from_name The from name
  • reply_to The reply to address
  • log Whether or not to log the email (default true)
  • log_masked_tags The tags to be masked when logging the email
Return values
bool —

Returns true if the message was successfully sent, false otherwise

sendCustom()

Sends a custom email using the criteria specified

public sendCustom(string $from, string $from_name, mixed $to, string $subject, array<string|int, mixed> $body[, array<string|int, mixed> $tags = null ][, mixed $cc = null ][, mixed $bcc = null ][, array<string|int, mixed> $attachments = null ][, array<string|int, mixed> $options = null ]) : bool
Parameters
$from : string

The email address to send from.

$from_name : string

The name to send from.

$to : mixed

The To address(es) to send to. A string, or an array of email addresses

$subject : string

The subject of the message. Tags provided in the subject will be evaluated by the template parser

$body : array<string|int, mixed>

An array containing the body in HTML and text of the email. Tags provided in the body will be evaluated by the template parser:

  • html The HTML version of the email (optional)
  • text The text version of the email (optional)
$tags : array<string|int, mixed> = null

An array of replacement tags containing the key/value pairs for the replacements where the key is the tag to replace and the value is the value to replace it with

$cc : mixed = null

The CC address(es) to send to. A string, or an array of email addresses

$bcc : mixed = null

The BCC address(es) to send to. A string, or an array of email addresses

$attachments : array<string|int, mixed> = null

A multi-dimensional array of attachments containing:

  • path The path to the attachment on the file system
  • name The name of the attachment (optional, default '')
  • encoding The file encoding (optional, default 'base64')
  • type The type of attachment (optional, default 'application/octet-stream')
$options : array<string|int, mixed> = null

An array of options including:

  • to_client_id The ID of the client the message was sent to
  • from_staff_id The ID of the staff member the message was sent from
  • reply_to The reply to address
  • log Whether or not to log the email (default true)
  • log_masked_tags The tags to be masked when logging the email
Return values
bool —

Returns true if the message was successfully sent, false otherwise

updateFromDomain()

Updates the domani portion of the from name for every email in the given company.

public updateFromDomain(string $domain, int $company_id) : mixed
Parameters
$domain : string

The new domain to use

$company_id : int

The ID of the company to update

validateAttachmentPaths()

Validates that the given attachments exist on the file system

public validateAttachmentPaths(mixed $attachments) : mixed
Parameters
$attachments : mixed

validateEmailAddresses()

Validates that each of the given email addresses provided are valid

public validateEmailAddresses(mixed $email_addresses) : bool
Parameters
$email_addresses : mixed
Return values
bool —

True if every email address is valid, false otherwise

validateEmailGroupAction()

Validates that the given action is a valid email group action

public validateEmailGroupAction(string $action) : bool
Parameters
$action : string

The email group action

Return values
bool —

True if the action is valid, false otherwise

validateParse()

Validate that the given string parses template parsing

public validateParse(string $str) : mixed
Parameters
$str : string

The string to test

validateSignatureExists()

Validates the email signature submitted exists and belongs to the company ID given

public validateSignatureExists(int $signature_id[, int $company_id = null ]) : bool
Parameters
$signature_id : int

The email signature ID

$company_id : int = null

The company ID (optional)

Return values
bool —

True if the signature exists and belongs to the company ID given, false otherwise

validateSignatureInUse()

Checks whether the email signature given is in use by any email

public validateSignatureInUse(int $signature_id) : bool
Parameters
$signature_id : int

The email signature ID

Return values
bool —

True if signature ID is in use, false otherwise

validateStatus()

Validates the emails 'status' field

public validateStatus(string $status) : bool
Parameters
$status : string

The status to check

Return values
bool —

True if status validated, false otherwise

validateUnique()

Validates the given company ID, email group ID, and language type are unique for this email

public validateUnique(int $company_id, int $email_group_id, string $lang) : bool
Parameters
$company_id : int

The company ID

$email_group_id : int

The email group ID

$lang : string

The language in ISO 636-1 2-char + "_"

  • ISO 3166-1 2-char (e.g. en_us) (optional, default en_us)
Return values
bool —

True if the given info is unique, false otherwise

getEmailRules()

Returns the rule set for adding/editing emails

private getEmailRules(array<string|int, mixed> $vars[, bool $edit = false ]) : array<string|int, mixed>
Parameters
$vars : array<string|int, mixed>

The key/value pairs of vars

$edit : bool = false

True when editing an email, false otherwise

Return values
array<string|int, mixed> —

Email rules

getEmails()

Constructs a partial Record query used to fetch emails

private getEmails() : Record
Return values
Record —

A partial Record query object used to fetch emails

getSendEmailRules()

Returns the rule set for adding/editing emails

private getSendEmailRules(array<string|int, mixed> $vars[, bool $custom = false ]) : array<string|int, mixed>
Parameters
$vars : array<string|int, mixed>

The key/value pairs of vars

$custom : bool = false

True to get the send custom email rules, false to get the default send email rules (optional, default false)

Return values
array<string|int, mixed> —

The send email rules

getSignatureRules()

Returns the rule set for adding/editing signatures

private getSignatureRules() : array<string|int, mixed>
Return values
array<string|int, mixed> —

Signature rules

getSignatures()

Partially constructs the query required by both Emails::getSignatureList() and Emails::getSignatureListCount()

private getSignatures(int $company_id) : Record
Parameters
$company_id : int

The company ID to fetch email for

Return values
Record —

The partially constructed query Record object

htmlToText()

Converts the given HTML to text if the given text contains no characters

private htmlToText(string $html[, string $text = '' ]) : string
Parameters
$html : string

The HTML to convert to text

$text : string = ''

The current text, if any

Return values
string —

The HTML converted to text, or the original text given

parse()

Parses an email and evaluates the tags on provided in the body

private parse(string $str[, array<string|int, mixed> $tags = [] ][, int $company_id = null ][, array<string|int, mixed> $options = [] ]) : string
Parameters
$str : string

The email HTML or text body to parse

$tags : array<string|int, mixed> = []

An array of replacement tags containing the key/value pairs for the replacements where the key is the tag to replace and the value is the value to replace it with

$company_id : int = null

The company ID to send this email under (optional)

$options : array<string|int, mixed> = []

An array with the options for the H2o parser (optional)

Return values
string —

The parsed email body

sendEmail()

Performs the heavy lifting to send the given email and log it.

private sendEmail(mixed $email[, mixed $email_masked = null ]) : mixed
Parameters
$email : mixed
$email_masked : mixed = null

setFilters()

Sets filters on the parser

private setFilters(object $parser, int $company_id) : mixed
Parameters
$parser : object

The parser to set filters on

$company_id : int

The company ID to set filters from

setParseError()

Sets the parse error in the set of errors

private setParseError() : mixed
Tags
subpackage

app.models

copyright

Copyright (c) 2010, Phillips Data, Inc.

license

http://www.blesta.com/license/ The Blesta License Agreement

link

Blesta

 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results