E-mail Action

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

E-mail Settings

Setting nameDescription
Action nameAlias name allowing to use targeted hook
FromThe sender e-mail address
Format: Name <email@domain.com>
ToThe recipient address
Reply toThe address to reply to
CcCopy carbon
BccBlind copy carbon
SubjectThe e-mail subject
ContentThe e-mail content
Dynamic filesE-mail attachments (mapping a field)
Static filesStatic e-mail attachments

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/validation/email hook and throw errors with the acfe_add_validation_error() function. Usage example:

/*
 * E-mail Validation
 * 
 * @array   $form     Form settings
 * @string  $post_id  Post ID (where the form is displayed)
 * @string  $action   Action name
 */
 
action('acfe/form/validation/email',                 $form, $post_id, $action);
action('acfe/form/validation/email/form=my-form',    $form, $post_id, $action);
action('acfe/form/validation/email/action=my-email', $form, $post_id, $action);
add_action('acfe/form/validation/email/form=my-form', 'my_form_validation', 10, 3);
function my_form_validation($form, $post_id, $action){
    
    // Get field input value
    $my_field = get_field('my_field');
    
    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. The acfe/form/prepare/email hook allows you to stop the Action early if necessary.

It is also the best place to add some logic or create new query vars that could be used within the Action UI. Returning false will stop the Action and go to the next one. Usage example:

/*
 * E-mail Prepare
 * 
 * @bool    $prepare  True/false
 * @array   $form     Form settings
 * @string  $post_id  Post ID (where the form is displayed)
 * @string  $action   Action name
 */
 
filter('acfe/form/prepare/email',                 $prepare, $form, $post_id, $action);
filter('acfe/form/prepare/email/form=my-form',    $prepare, $form, $post_id, $action);
filter('acfe/form/prepare/email/action=my-email', $prepare, $form, $post_id, $action);
add_filter('acfe/form/prepare/email/form=my-form', 'my_form_prepare', 10, 4);
function my_form_prepare($prepare, $form, $post_id, $action){
    
    // Get field input value
    $my_field = get_field('my_field');
    
    // Create custom message
    $message = 'This is a custom message. Field value: ' . $my_field;
    
    // Retrive the message using {query_var:email_message} in the Email Action UI
    set_query_var('email_message', $message);
    
    // Do not send e-mail if user isn't logged in
    if(!is_user_logged_in()){
        
        $prepare = false;
        
    }
    
    // return
    return $prepare;
    
}

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 Arguments
 * 
 * @array   $args    Email arguments
 * @array   $form    Form settings
 * @string  $action  Action name
 */
 
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/action=my-email', 'my_form_email_args', 10, 3);
function my_form_email_args($args, $form, $action){
    
    /*
     * $args = array(
     *     'from'          => 'email@domain.com',
     *     'reply_to'      => 'email@domain.com',
     *     'to'            => 'email@domain.com',
     *     'cc'            => 'email@domain.com',
     *     'bcc'           => 'email@domain.com',
     *     'subject'       => 'Subject',
     *     'content'       => 'Content',
     *     'headers'       => array(
     *         'From: email@domain.com',
     *         'Reply-to: email@domain.com',
     *         'Cc: email@domain.com',
     *         'Bcc: email@domain.com',
     *         'Content-Type: text/html',
     *         'charset=UTF-8'
     *     ),
     *     'attachments'   => array(
     *         '/path/to/file.jpg'
     *     )
     * );
     */
    
    // Get field input value
    $my_field = get_field('my_field');
    
    if($my_field === 'Company'){
    
        // Change 'from' field
        $args['from'] = 'user@domain.com';
    
    }

    // Do not send e-mail
    // return false;
    
    // return
    return $args;
    
}

Submit

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

/*
 * E-mail Submit
 * 
 * @array   $args    Email arguments
 * @array   $form    Form settings
 * @string  $action  Action name
 */
 
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_form_submit', 10, 3);
function my_form_submit($args, $form, $action){
    
    // Get field input value
    $my_field = get_field('my_field');
    
    if($my_field === 'Company'){
    
        // Do something...
    
    }
    
}

Query Var

After the action completion, a query var with the e-mail arguments is automatically genereated. This query var is useful to retrieve the action information in the UI using {query_var:my-email-action:from} or in PHP using get_query_var('my-email-action')['from'].

If the action is named, the query var will simply use its name: my-email-action. If there is no action name, it will be named my-form-email . If there are multiple e-mails actions without names, the second e-mail query var will be called my-form-email-2 and so on.

The acfe/form/query_var/email hook allows you to change the data that is returned. Usage example:

/*
 * E-mail Query var
 * 
 * @array   $data    Email arguments
 * @array   $form    Form settings
 * @string  $action  Action name
 */
 
filter('acfe/form/query_var/email',                 $data, $form, $action);
filter('acfe/form/query_var/email/form=my-form',    $data, $form, $action);
filter('acfe/form/query_var/email/action=my-email', $data, $form, $action);
add_filter('acfe/form/query_var/email/form=my-form', 'my_form_query_var', 10, 3);
function my_form_query_var($data, $form, $action){
    
    /*
     * $data = array(
     *     'from'          => 'email@domain.com',
     *     'reply_to'      => 'email@domain.com',
     *     'to'            => 'email@domain.com',
     *     'cc'            => 'email@domain.com',
     *     'bcc'           => 'email@domain.com',
     *     'subject'       => 'Subject',
     *     'content'       => 'Content',
     *     'headers'       => array(
     *         'From: email@domain.com',
     *         'Reply-to: email@domain.com',
     *         'Cc: email@domain.com',
     *         'Bcc: email@domain.com',
     *         'Content-Type: text/html',
     *         'charset=UTF-8'
     *     ),
     *     'attachments'   => array(
     *         '/path/to/file.jpg'
     *     )
     * );
     */
    
    // Get field input value
    $my_field = get_field('my_field');
    
    if($my_field === 'Company'){
    
        // Set a custom key
        $data['custom_key'] = 'custom_value';
    
    }
    
    // return
    return $data;
    
}