Software Developer

Add a MailChimp API Version 3.0 Signup Form To WordPress Without a Plugin

This is the most lightweight way to add a MailChimp email signup form using their API v3.0. This uses only 89 lines of code, no plugin.

This lightweight MailChimp subscription form assumes you want users to subscribe to your email list. This code disables “Double Opt-in” which means that users will NOT be sent a confirmation email after signing up. They just have to enter their email once, and they’ll be immediately subscribed to your list.

You can set up this MailChimp signup form in a matter of minutes with these 3 fairly simple steps.

You will need your MailChimp “List ID” and your MailChimp API key. To get your API key, log in to MailChimp. Click on your name in the top right corner, then click “Account.” Click on “Extras” to open the drop-down, then click “API keys.” Under the “Your API keys” section, click “Create A Key.” Your new API key should appear. Copy that, as you’ll need to add it in the code below.

This code uses version 3.0 of the MailChimp API. Many WordPress plugins are still using version 2, which is deprecated.

Step 1

Step 1 is to add the function that will process the sign up form and subscribe users to your MailChimp list. This code goes in your functions file (whether you use a child theme’s functions.php, or a custom plugin, or other functions file).

You must edit lines 15 and 16. Replace YOUR_API_KEY with your own MailChimp API key. Replace YOUR_LIST_ID with your own MailChimp list ID.

Code block 1A

/**
 * Process the MailChimp newsletter subsription form and subscribe user to list.
 */
function acme_process_newsletter_subscription() {
	// Block spam bots
	if ( ! empty( $_POST['pooh_hundred_acre_wood_field'] ) ) {
		return false;
	}
	if ( empty( $_POST['EMAIL'] ) ) {
		return;
	}

	// Configure --------------------------------------

	$api_key = 'YOUR_API_KEY';
	$list_id = 'YOUR_LIST_ID';

	// STOP Configuring -------------------------------

	$redirect_to = isset( $_POST['redirect_to'] ) ? $_POST['redirect_to'] : home_url();
	$msg = 'error';
	$api_endpoint = 'https://<dc>.api.mailchimp.com/3.0/';
	list(, $datacenter) = explode( '-', $api_key );
	$api_endpoint = str_replace( '<dc>', $datacenter, $api_endpoint );
	$url = $api_endpoint.'/lists/' . $list_id . '/members/';
	$body = array(
		'email_address' => sanitize_email( $_POST['EMAIL'] ),
		'status' => 'subscribed'
	);
	$request_args = array(
		'method'      => 'POST',
		'timeout'     => 20,
		'headers'     => array(
			'Content-Type' => 'application/json',
        	'Authorization' => 'apikey ' . $api_key
		),
		'body'        => json_encode( $body ),
	);
	$request = wp_remote_post( $url, $request_args );
	$subscribe = is_wp_error( $request ) ? false : json_decode( wp_remote_retrieve_body( $request ) );
	if ( $subscribe ) {
		if ( isset( $subscribe->title ) && 'Member Exists' == $subscribe->title ) {
			$msg = 'exists';
		} elseif ( 'subscribed' == $subscribe->status ) {
			$msg = 'success';
		}
	}
	wp_redirect( esc_url_raw( add_query_arg( 'acme_signup', $msg, $redirect_to ) ) );
	exit;
}

add_action( 'admin_post_nopriv_acme_newsletter_subscription', 'acme_process_newsletter_subscription' );
add_action( 'admin_post_acme_newsletter_subscription', 'acme_process_newsletter_subscription' );

Step 2

Step 2 is to display the actual sign-up form somewhere on your site. There are several ways that you can do this. The easiest way is possible if you have a good theme that has hooks available for you to hook your custom things to. For example, the default WordPress Twenty Sixteen theme has a hook in the footer which lets you add stuff to your site’s footer. The hook is twentysixteen_credits.

(Unfortunately, the WordPress Twenty Seventeen does not have any good hooks.)

The following example will show the form on the footer if you’re using Twenty Sixteen theme. You can see the twentysixteen_credits hook on the first line:

Code block 2A

add_action( 'twentysixteen_credits', 'acme_show_mailchimp_form' );
/**
 * Display the MailChimp newsletter signup form.
 */
function acme_show_mailchimp_form() {
	if ( is_singular() ) {

		$title = 'Get Free Updates';
		$description = 'Be the first to know about discounts, sales, and promotions.';
		$submit_text = 'Sign me up!';

		global $post;
		$redirect_to = get_permalink( $post->ID ) . '#acme-newsletter-wrap';
		// Display possible messages to the visitor.
		$message = '';
		if ( isset( $_GET['acme_signup'] ) ) {
			$class = 'success';
			if ( 'success' == $_GET['acme_signup'] ) {
				$response 	= 'Subscription successful.';
			} elseif ( 'exists' == $_GET['acme_signup'] ) {
				$response 	= 'Your email address was already subscribed.';
			} else {
				$response 	= 'Sorry, subscription was not successful. Please try again.';
				$class 		= 'error';
			}
			$message = '<p class="acme-alert acme-alert-' . $class . '">' . $response . '</p>'; 
		}
		?>
		<div id="acme-newsletter-wrap">
			<h3><?php echo $title; ?></h3><p><?php echo $description; ?></p>
	        <form action="<?php echo esc_url( admin_url('admin-post.php') ); ?>" method="post" id="acme-mc-subscribe-form" name="acme-mc-subscribe-form">
	        	<?php echo $message; ?><div class="mc-email clear">
	    	    <input type="email" value="" name="EMAIL" id="mce-EMAIL" placeholder="Email address" required>
	        	<input type="submit" value="<?php echo $submit_text; ?>" name="subscribe" id="mc-embedded-subscribe" class="button"></div>
	        	<div style="position: absolute; left: -5000px;" aria-hidden="true"><input type="text" name="pooh_hundred_acre_wood_field" tabindex="-1" value=""></div>
				<input type="hidden" name="action" value="acme_newsletter_subscription">
	        	<input type="hidden" name="redirect_to" value="<?php echo $redirect_to; ?>">
        	</form>
    	</div>
        <?php
	}
}

You can optionally edit the text within the quotes on lines 8, 9, and 10 above.

  • Line 8 is a title that will show above the form.
  • Line 9 is a sentence that will be shown above the form. It should entice your readers to sign up.
  • Line 10 is the button text that will appear on the form’s submit button.

Most of you are not using the Twenty Sixteen theme. If your theme has a hook that you can use to display stuff, then simply replace twentysixteen_credits on line 1, above, with your own theme’s hook. For example, your theme may have a hook called “ACME_THEME_FOOTER” or “ACME_THEME_SIDEBAR”. If you found a good hook, and the MailChimp form is displayed on your site, then skip down to Step 3.

If your theme doesn’t have any good hook for you to add this MailChimp form, then you have other options for displaying the form.

A second option is to use it as a shortcode. In this case, don’t use code block 2A above. Instead, create the shortcode for the MailChimp signup form by adding this code to your functions:

Code block 2B

function acme_mailchimp_form_shortcode( $atts ) {

	$out = '';

	$title = 'Get Free Updates';
	$description = 'Be the first to know about discounts, sales, and promotions.';
	$submit_text = 'Sign me up!';

	global $post;
	$redirect_to = get_permalink( $post->ID ) . '#acme-newsletter-wrap';

	// Display possible messages to the visitor.
	$message = '';
	if ( isset( $_GET['acme_signup'] ) ) {
		$class = 'success';
		if ( 'success' == $_GET['acme_signup'] ) {
			$response 	= 'Subscription successful.';
		} elseif ( 'exists' == $_GET['acme_signup'] ) {
			$response 	= 'Your email address was already subscribed.';		
		} else {
			$response 	= 'Sorry, subscription was not successful. Please try again.';
			$class 		= 'error';
		}
		$message = '<p class="acme-alert acme-alert-' . $class . '">' . $response . '</p>'; 
	}
	$out .= '<div id="acme-newsletter-wrap"><h3>' . $title . '</h3><p>' . $description . '</p>
		<form action="' . esc_url( admin_url( 'admin-post.php' ) ) . '" method="post" id="acme-mc-subscribe-form" name="acme-mc-subscribe-form">' . $message . '<div class="mc-email clear">
	<input type="email" value="" name="EMAIL" id="mce-EMAIL" placeholder="Email address" required>
	<input type="submit" value="' . $submit_text . '" name="subscribe" id="mc-embedded-subscribe" class="button"></div>
    <div style="position: absolute; left: -5000px;" aria-hidden="true"><input type="text" name="pooh_hundred_acre_wood_field" tabindex="-1" value=""></div>
		<input type="hidden" name="action" value="acme_newsletter_subscription">
        <input type="hidden" name="redirect_to" value="' . $redirect_to . '"></form></div>';

	return $out;
}
add_shortcode( 'acme_mailchimp_form', 'acme_mailchimp_form_shortcode' );

 
Then, you can use the shortcode [acme_mailchimp_form] wherever you want to display the form. If you’ve added the shortcode to a widget, and you notice that it’s not working on the front of your site, then you must add this line to the code above (to code block 2B):

add_filter('widget_text', 'do_shortcode');// Enable shortcodes in widgets

If this shortcode works and the MailChimp form is displayed on your site, skip down to Step 3.

 

If you don’t like the shortcode idea, a third option is to add the form to every post, below the content. This is done by adding a filter to the content. To do this, use Code Block 2B, but make these 2 changes:

  • Change line 1 to this:

    function acme_show_mailchimp_form_below_content( $content ) {
  • Change lines 34–36 to this:

        return $content . $out;
    }
    add_filter( 'the_content', 'acme_show_mailchimp_form_below_content', 9999 );
    

 

Yet a fourth option is to add the form’s code directly into your theme’s template files, wherever you want the form to appear. In this case, take lines 8–39 of code block 2A and paste them in your template file wherever you want. If you do this, then you must insert an opening PHP tag at the beginning of this code block. An opening PHP tag looks like this:

<?php

Step 3

Step 3 is to add CSS styles. This is optional, but it will provide a better user experience if the success response message is green, and if the error message is red. Otherwise, the user may not immediately be able to tell if anything happened after they submitted their email address. Add the following CSS to style the response messages. (It’s very easy to add custom CSS to your WordPress site.)

/* MAILCHIMP Subscription Form
-------------------------------------------------------------- */
.acme-alert {
	border-radius: 2px;
	margin-bottom: 20px;
	padding: 10px;
  	vertical-align: middle;
	background-color: #DFF2BF;
	color: #4F8A10;

}
.acme-alert-error {
	color: #D8000C;
	background-color: #FFBABA;
}

The following CSS styles are really optional. These are to style the form like the picture at the top of this page, in which the submit button is stuck to the right side of the input box.

/* Optional - MAIL CHIMP Subscription Form */
#acme-newsletter-wrap {
	text-align: center;
	max-width: 450px;
	margin: 0 auto;
	padding: 60px 10px;
}
#acme-mc-subscribe-form input {
	float: left;
	margin: 0;
	padding: 14px 12px;
	border-radius: 4px 0 0 4px;
	width: 70%;
	height:50px;
}

#acme-mc-subscribe-form #mc-embedded-subscribe {
	padding: 10px;
	font-size:11px;	
	border: none;
	border-radius: 0 4px 4px 0;
	transition: all .2s ease-in-out;
	width: 23%;
}

@media screen and (max-device-width:768px) {
	#acme-mc-subscribe-form input {
		padding: 12px 3px;
	}
	
	#acme-mc-subscribe-form #mc-embedded-subscribe {
		padding: 10px 0;
	}
}

Optional Step 4

Step 4 is completely optional. The examples on this page all use the prefix “acme” as a namespace. You can change “acme” to your own prefix. If you do change it, be sure to change it EVERWHERE for all code examples on this page, including the CSS. Be sure to leave dashes and underscores as they are.

By

We've 3 Responses

  1. June 9th, 2017 at 8:31 pm

    Hi, Congratulations on the article, it works great. I think it would be interesting to add the double confirmation option, as some studies indicate that the double-confirm method is more effective in getting subscribers really interested in subscribing. Thanks for sharing. Greetings,

    avatar
  2. May 16th, 2018 at 6:09 am

    Great! it works like a charm, but I think like Alba that would be grate to add the double confirmation option. I can’t see in your code where are you disabling it.

    avatar

Leave a Reply to Alba Cancel reply

Your email address will not be published. All comments will be moderated.

Please wrap code in "code" bracket tags like this:

[code]

YOUR CODE HERE 

[/code]