E-mail Action FREE

#E-mail Action

The Email Action is a template to generate and send advanced e-mails on form submission.

#E-mail Settings

#Validation

By default, there is no validation for this Action. You can use the acf/validate_value hook to validate each fields individually.

To validate the whole form, you can use the acfe/form/validate_email hook and throw errors with the acfe_add_validation_error() function. Usage example:

/**
 * E-mail Action: Validation
 * 
 * @array  $form    Form settings array
 * @array  $action  Action settings array
 */
 
action('acfe/form/validate_email',                 $form, $action);
action('acfe/form/validate_email/form=my-form',    $form, $action);
action('acfe/form/validate_email/action=my-email', $form, $action);

add_action('acfe/form/validate_email/form=my-form', 'my_email_validation', 10, 2);
function my_email_validation($form, $action){
    
    // get current post id
    // where the form is displayed
    $post_id = $form['post_id'];
    
    // get field input value
    $my_field = get_field('my_field');
    
    // check field value
    if($my_field === 'Company'){
        
        // add validation error
        acfe_add_validation_error('my_field', 'The value Company is not allowed');
        
    }
    
}

#Prepare

The preparation phase is triggered after the form validation and before its submission. Returning false will stop the Action and go to the next one. Usage example:

/**
 * E-mail Action: Prepare
 * 
 * @array  $action  Action settings array
 * @array  $form    Form settings array
 *
 * @return array|false
 */
 
filter('acfe/form/prepare_email',                 $action, $form);
filter('acfe/form/prepare_email/form=my-form',    $action, $form);
filter('acfe/form/prepare_email/action=my-email', $action, $form);

add_filter('acfe/form/prepare_email/form=my-form', 'my_email_prepare', 10, 2);
function my_email_prepare($action, $form){
    
    // if user isn't logged in
    // do not send the e-mail
    if(!is_user_logged_in()){
        return false;
    }
    
    // return normally
    return $action;
    
}

#E-mail Arguments

The acfe/form/submit_email_args hook let you change the e-mail arguments right before it is sent by wp_mail(). Returning false will stop the e-mail from being sent. Usage example:

/**
 * E-mail Action: Arguments
 * 
 * @array  $args    E-mail arguments
 * @array  $form    Form settings array
 * @array  $action  Action settings array
 * 
 * @return array|false
 */
 
filter('acfe/form/submit_email_args',                 $args, $form, $action);
filter('acfe/form/submit_email_args/form=my-form',    $args, $form, $action);
filter('acfe/form/submit_email_args/action=my-email', $args, $form, $action);

add_filter('acfe/form/submit_email_args/form=my-form', 'my_email_args', 10, 3);
function my_email_args($args, $form, $action){
    
    /**
     * $args = array(
     *     'from'          => '[email protected]',
     *     'reply_to'      => '[email protected]',
     *     'to'            => '[email protected]',
     *     'cc'            => '[email protected]',
     *     'bcc'           => '[email protected]',
     *     'subject'       => 'Subject',
     *     'content'       => 'Content',
     *     'headers'       => array(
     *         'From: [email protected]',
     *         'Reply-to: [email protected]',
     *         'Cc: [email protected]',
     *         'Bcc: [email protected]',
     *         'Content-Type: text/html',
     *         'charset=UTF-8'
     *     ),
     *     'attachments'   => array(        // must use server files path
     *         '/path/to/file.jpg',
     *         '/path/to/file-2.jpg',
     *     )
     *     'delete_files'  => array(45, 46) // must use attachement ids
     * );
     */
    
    // get the form input value
    $my_field = get_field('my_field');
    
    // check field value
    // and change recipient
    if($my_field === 'Company'){
        $args['to'] = '[email protected]';
    }

    // get previous post action output (if any)
    // retrieve the 'post_title' specifically
    $post_title = acfe_get_form_action('post.post_title');
    
    // check the post title
    // and change the recipient
    if($post_title === 'My Post'){
        $args['to'] = '[email protected]';
    }

    // do not send the e-mail
    // return false;
    
    // return normally
    return $args;
    
}

#Submit

Trigger a custom action after the e-mail was sent using the acfe/form/submit_email hook. Usage example:

/**
 * E-mail Action: Submit
 * 
 * @array  $args    E-mail arguments array
 * @array  $form    Form settings array
 * @array  $action  Action settings array
 */
 
action('acfe/form/submit_email',                 $args, $form, $action);
action('acfe/form/submit_email/form=my-form',    $args, $form, $action);
action('acfe/form/submit_email/action=my-email', $args, $form, $action);

add_action('acfe/form/submit_email/form=my-form', 'my_email_submit', 10, 3);
function my_email_submit($args, $form, $action){
    
    // get current post id
    // where the form is displayed
    $post_id = $form['post_id'];
    
    // get field input value
    $my_field = get_field('my_field');

    // check field value
    if($my_field === 'Company'){
        // do something
    }

    // get previous post action output (if any)
    // retrieve the 'post_title' specifically
    $post_title = acfe_get_form_action('post.post_title');
    
    // check the post title
    if($post_title === 'My Post'){
        // do something
    }
    
}

#Output

The Action Output allows retrieve the action data in a future action within the Form UI using a Template Tag, or a PHP hook using a function.

For example, the Template Tag {action:email:content} will output the latest E-mail “Content”. The equivalent in PHP is acfe_get_form_action('email.content').

It is possible to change the output of an E-mail Action using the acfe/form/submit_email_output filter. Usage example:

/**
 * E-mail Action: Output
 * 
 * @array  $output  E-mail arguments array
 * @array  $form    Form settings array
 * @array  $action  Action settings array
 *
 * @return array
 */
 
filter('acfe/form/submit_email_output',                 $output, $form, $action);
filter('acfe/form/submit_email_output/form=my-form',    $output, $form, $action);
filter('acfe/form/submit_email_output/action=my-email', $output, $form, $action);

add_filter('acfe/form/submit_email_output/form=my-form', 'my_email_output', 10, 3);
function my_email_output($output, $form, $action){
    
    /**
     * $output = array(
     *     'from'          => '[email protected]',
     *     'reply_to'      => '[email protected]',
     *     'to'            => '[email protected]',
     *     'cc'            => '[email protected]',
     *     'bcc'           => '[email protected]',
     *     'subject'       => 'Subject',
     *     'content'       => 'Content',
     *     'headers'       => array(
     *         'From: [email protected]',
     *         'Reply-to: [email protected]',
     *         'Cc: [email protected]',
     *         'Bcc: [email protected]',
     *         'Content-Type: text/html',
     *         'charset=UTF-8'
     *     ),
     *     'attachments'   => array(
     *         '/path/to/file.jpg'
     *     )
     * );
     */
    
    // get field input value
    $my_field = get_field('my_field');
    
    // check field value
    if($my_field === 'Company'){
    
        // set a custom key/value pair in the output
        $output['custom_key'] = 'custom_value';
    
    }
    
    // return normally
    return $output;
    
}