Emails

Emails Module allows notifying users and administrators by email when various actions occur, for example, the module can send an email to admin to let him know that a user has published an Advert using [adverts_add] shortcode.

Installation and Configuration

The Emails Module is available in the free WPAdverts plugin since version 1.3.0. If you are using older WPAdverts version then in order to use it you will need to update WPAdverts first and then enable Emails Module from wp-admin / Classifieds / Options panel.

The main Emails configuration screen looks like on the image below

The email templates list has 3 columns:

• Clickable Email Subject  it will take you to the email edit page (described below)
• Code this column list unique email code and a link to the email documentation, basically a link to a page which explains when this message is sent and what variables are available in the email.
• Activity informs if the email is email template is enabled, if not then the message will not be sent

From this page, you can either edit an email template or click “Options” tab which will take you to a page with few options.

Options

Send Admin Notifications To – in this field you can enter an email address to which all the Administrator notifications will be sent. You can overwrite this value for each email while editing the template.

HTML Emails – by default Emails Module sends all messages in plain text format. Checking the HTML Emails checkbox will make the WPAdverts send emails as text/html. More specifically it will add a ‘Content-Type: text/html; charset=utf-8’ header to each email and enable visual editor in the email template “Message Body” field.

Emails Edition

The email edition form has a couple of fields which allow customizing the email templates any way you want.

Email Name – For reference at the top of the form there is the unique email template name and a link to the documentation.

Subject – Allows changing the default email subject.

From – In this field you can enter the Name and Email, these values will be visible in “From” field in the inbox of the user who will receive this message.

ProTip: To make sure your emails are always delivered it is best to fist configure email delivery via SMTP, you can do that using a plugin like WP Mail SMTP, and then for each email in the field From set name and email address of the SMTP account you are using.

To – To whom this message should be sent.

You probably noticed the value in this field is not an email but rather a {$advert|contact_email} string. This is a variable we want to send the confirmation email to a user who published the Advert (usually this will be a different email address for each Ad), so we are using {$advert|contact_email} variable which before sending the message will be automatically replaced with an actual email address. The variables are described in more detail below.

Add Header button – By default, the message has few headers only (From, To, Subject, and optionally Content-Type). If you would like to include some custom header in then you can do that by clicking the “Add Header” button, it will show a form like on the image below

To add the header just fill the “Header Name” and header value fields (you can use variables) and click OK icon or X to discard the entry.

Body – In this field, you can fill the message body. By default, this field is a simple textarea but if you enable HTML Emails in the options it will be displayed as a visual editor.

Attachments – This field allows attaching files to the message. The most basic use is to click on the “Add Attachment” button and enter an exact path to the file. Note that you need to pass a path to the file on your server NOT a link.

It is also possible to use {$advert_files} or {$form_files} variable (where available) to pass files attached to the Advert or uploaded to a form.

The “Update Options” saves the message.

Email Templates

Below you can list of email templates available by default in WPAdverts and links to other modules and extensions documentation that integrate with Emails Module.

core::on_draft_to_publish_notify_user

This message is sent to a user who published a free Ad from a page with [adverts_add] shortcode.

Available variables: {$advert} {$advert_files}

core::on_draft_to_pending_notify_user

This message is sent to a user who posted a free Ad from a page with [adverts_add] shortcode, the Ad is put into moderation and will not be visible until the administrator approves it.

Available variables: {$advert} {$advert_files}

core::on_pending_to_publish_notify_user

This message is sent to the user when the Administrator approved his Ad to inform the user that his Advert is now published and available on site. (The message is sent only when the Ad was saved as pending/moderated.)

Available variables: {$advert} {$advert_files}

core::on_pending_to_trash_notify_user

This message is sent to the user when the Administrator trashes his Ad to inform the user that his Advert was rejected. (The message is sent only when the Ad was saved as pending/moderated.)

Available variables: {$advert} {$advert_files}

core::on_publish_to_expired_notify_user

This message notifies Ad owner that his Ad expired and is no longer available on site.

Available variables: {$advert} {$advert_files}

core::on_draft_to_publish_notify_admin

This message notifies Administrator that the user has published a new Advert from a page with [adverts_add] shortcode and the new Ad is visible on site.

Available variables: {$advert} {$advert_files}

core::on_draft_to_pending_notify_admin

This message notifies Administrator that the user has posted a new Advert from a page with [adverts_add] shortcode and the Ad requires moderation.

Available variables: {$advert} {$advert_files}

Integrations

Some WPAdverts modules and extensions can integrate with Emails Module by adding new messages to wp-admin / Classifieds / Options / Emails list.

Currently, the following modules have the integration ready:

• Payments Module – can send messages when paid Ad is posted or payment created and paid.
• Contact Form – allows customizing message sent when the user submits a contact form.

Registering New Email Templates

wpadverts_messages_register

Variables

In all the email template fields (including headers) you can use variables to insert dynamic data inside the email.

The variables are in the following format {$variable} if a variable is an array or object you can access it properties by using dot, for example, if {$variable} is defined as below

$variable = array( "test" => "ok", 1 => array( "test2" => "also ok" ) );

Then entering in the email body {$variable.test} will display “ok” and entering {$variable.1.test2} will display “also ok”.

Functions

The variables before displaying in the message can be filtered by functions. You can use any of the PHP functions (assuming the first argument the function accepts will be variable itself).

To execute a function separate the function name from variable name using “|” char, for example using {$variable.test|strtoupper} will display “OK” (the string was converted to uppercase letters).

Functions with additional params

If the function accepts more than one argument you can pass the arg by separating a function name from the argument using “:”, for example {$variable.test|str_repeat:2} will return “okok”.

The variable above is equivalent of running in PHP this code

<?php echo str_repeat( $variable["test"], 2 ) ?>

Chaining function calls

That’s not all, you can call a function chain by adding multiple functions after the variable like this {$variable.test|strtoupper|str_repeat:2} the result should be “OKOK”.

Custom Functions

Aside of using the default PHP and WordPress functions, it is also possible to register your own custom functions which you will be able to call from the email templates.

For example, let’s register a custom function which will repeat string 3 times and append “…” at the end of the string. The new function we will be registering in “init” action to make sure the Emails module is loaded.

add_action( "init", "custom_emails_func", 20 );
function custom_emails_func() {
    if( class_exists( "Adext_Emails" ) ) {
        Adext_Emails::instance()->parser->add_function( "my_func", "custom_emails_func_callback" );
    }
}
function register_custom_emails_func_callback( $data ) {
    return str_repeat( $data, 3 ) . " ...";
}

Now you can call this function in an email template like this {$variable.test|my_func} it should display “okokok …”;

Common Variables

There are few variables which are available in most of the emails, instead describing them several times here is documentation for those variables instead

{$advert}

This is basically a WP_Post object so you can access the same properties as in the WP_Post and the properties will return values formatted as in WP_Post

{$advert.ID}                   (int)    - The ID of the post
{$advert.post_author}          (string) - The post author's user ID (numeric string)
{$advert.post_name}            (string) - The post's slug
{$advert.post_type}            (string) - Post Type in this case it is always 'advert'
{$advert.post_title}           (string) - The title of the post
{$advert.post_date}            (string) - Format: 0000-00-00 00:00:00
{$advert.post_date_gmt}        (string) - Format: 0000-00-00 00:00:00
{$advert.post_content}         (string) - The full content of the post
{$advert.post_excerpt}         (string) - User-defined post excerpt
{$advert.post_status}          (string) - Usually one of: publish, draft, expired, pending
{$advert.comment_status}       (string) - One of: open, closed
{$advert.ping_status}          (string) - One of: open, closed
{$advert.post_password}        (string) - Returns empty string if no password
{$advert.post_parent}          (int)    - Parent Post ID (default 0)
{$advert.post_modified}        (string) - Format: 0000-00-00 00:00:00
{$advert.post_modified_gmt}    (string) - Format: 0000-00-00 00:00:00
{$advert.comment_count}        (int)    - Number of comments on post (numeric string)
{$advert.menu_order}           (int)    - If greater than 0 the post is featured

You can also use the $advert variable to access Ad metadata, to do that you can use the custom get_meta function.

By default there are 4 custom fields “adverts_location”, “adverts_price”, “adverts_email” and “adverts_person”, you can access them all with the code below

{$advert|meta:adverts_location}  // "New York"
{$advert|meta:adverts_price}     // 10000 (note this is price in cents)
{$advert|meta:adverts_email}     // "user@example.com"
{$advert|meta:adverts_person}    // "John Doe"

If you have some custom fields registered using Custom Fields extension or using the Forms API, you can also access them similarly as above, just replace the custom fields name with your actual custom fields names.

There are also some functions you can use to get a formatted data, for example in most of the cases you will want to get the formatted price not just the number of cents

{$advert|contact_email} - Either email address entered in Contact Email field or User email address if Ad was posted by a registered user
{$advert|price} - Formated Ad price
{$advert.ID|get_permalink} - URL to the Advert
{$advert|admin_edit_ur} - URL to the Ad edit page in wp-admin / Classifieds panel
{$advert.post_date|format_date} - Formats date using the format set in wp-admin / Settings panel

 

{$advert_files}

This variable contains information about the files attached to the advert, you can use it inside the “Attachments” field (see the Emails Edition section above in this article) to attach an advert file to the message.

By default this variable will have information about the files uploaded to the “gallery” field, if you have more file fields added to the [adverts_add] form then this information will be available there.

Assuming you have few files uploaded to the gallery you can attach them with the following code

{$advert_files.gallery|get_all_files}

The get_all_files is a function which will get directs path on the server to the uploaded files. Similarly, if you have in a form for example a file upload field named more_files, then you can attach them in the email by just replacing in the above snippet “gallery” with “more_files”.

 

Troubleshooting

Couple of problems you might experience while using the Emails Module.

Emails are not sent

When one or more of the email templates are not delivered to your inbox the first thing you should do is install a plugin like an Email Log and check if the emails are not sent or not delivered.

If the message is logged and the To header is set your email address then in most cases the message was sent but discarded by the email server (because it had low credibility score). To work around it you will need to configure email delivery via SMTP, you can do that using a plugin like WP Mail SMTP.