Action: E-mail

Features Modules Forms Action: E-mail

E-mail Action

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

Dynamic Form

Add actions on form submission

Click the "Add action" button below to start creating your layout
0 Custom action
Documentation
Action

Set a unique action slug.

0 Email action
0 Option action
Documentation
Action

(Optional) Target this action using hooks.

Save
Load

Fill inputs with values

0 Post action
Documentation
Action

(Optional) Target this action using hooks.

Save
Click to initialize TinyMCE
Load

Fill inputs with values

0 Redirect action
Documentation
Action

(Optional) Target this action using hooks.

The URL to redirect to. See "Cheatsheet" tab for all available template tags.

0 Term action
Documentation
Action

(Optional) Target this action using hooks.

Save
Click to initialize TinyMCE
Load

Fill inputs with values

0 User action
Documentation
Action

(Optional) Target this action using hooks.

Save
Click to initialize TinyMCE
Load

Fill inputs with values

1 Email action
Add action

E-mail Settings

Setting nameDescription
Action nameAlias name allowing to use targeted hook
FromThe sender e-mail address
Format: Name <[email protected]>
ToThe recipient address
Reply toThe address to reply to
CcCopy carbon
BccBlind copy carbon
SubjectThe e-mail subject
ContentThe e-mail content
Content TypeSwitch from WYSIWYG Editor/Raw HTML
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/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(
     *         '/path/to/file.jpg'
     *     )
     * );
     */
    
    // 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)
    $post_action = acfe_form_get_action('post');

    // check previous post action exists
    if(!empty($post_action)){
    
        // check the post title of the created post
        // and change the recipient
        if($post_action['post_title'] === 'Post Title'){
            $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)
    $post_action = acfe_form_get_action('post');
    
    // check previous post action exists
    if(!empty($post_action)){
    
        // get the post title of the created post
        if($post_action['post_title'] === 'Post Title'){
            // do something
        }

    }
    
}

Output

The Action Output let developers retrieve the action data in a future action within the Form UI or a PHP hook. For example, the Template Tag {action:email:content} will output the latest E-mail Action “Content” setting.

If the action is named, the Template Tag will use it. Ie: {action:my-email:content}. The equivalent function in PHP is acfe_form_get_action('email').

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;
    
}
Index
E-mail Action
E-mail Settings
Validation
Prepare
E-mail Arguments
Submit
Output
Functions
acfe_add_validation_error()
Hooks
acfe/form/validate_email
acfe/form/prepare_email
acfe/form/submit_email_args
acfe/form/submit_email
acfe/form/submit_email_output
Screenshots
Field Groups Field Settings Fields Modules
Block Types PRO Classic Editor PRO Developer Mode PRO Forms PRO
Integration PRO Cheatsheet Helpers Hooks Action: Custom Action: E-mail Action: Option PRO Action: Post Action: Redirect Action: Term Action: User
Options Pages PRO Performance Mode PRO Post Types PRO Rewrite Rules PRO Scripts PRO Settings UI PRO Taxonomies PRO Templates PRO
WordPress Hooks & Helpers