FORUMS


The Form Tools forums are no longer active, but the old posts have been archived here. Please see the Help page on how to get help / report issues.

Thread Rating:
  • 1 Vote(s) - 5 Average
  • 1
  • 2
  • 3
  • 4
  • 5
Integrating A MailChimp Newsletter Option
#1
.
.
Instructions for Integrated MailChimp Newsletter Signup to a FormTools Form

Note: This set of instructions does not use MailChimps double opt-in option. With a little research using the links provided at the end, I'm confident that someone will be able to implement that as an additional feature and post a reply here.

2013-08-22
UPDATE: I am still using Mail Chimp API v1.3.2 for this post.
UPDATE: Added "OPTIN_TIME" code. Added resource to bottom.
UPDATE: Added step 3a (to verify merge tags).


1) Download the proper API Wrapper for MailChimp.
For PHP forms, scroll to the PHP scetion of the following link and download MCAPI v{current}. Make sure you are using the most up-to-date version. I suggest putting this in a well-organized folder structure, so you'll understand what it is when you look at it next year.

(ie: Design Work\FormTools\MailChimp API Addition\MailChimp API Wrappers\MCAPI v1.3.2 (PHP)\PHP wrapper full\{extracted files})

MailChimp API Wrappers: http://apidocs.mailchimp.com/api/downloads/#php


2) Upload the MailChimp API to your web site.
In your web site structure, add a new directory inside the FormTools directory, called /mailchimp/. Upload the MCAPI.class.php file from Step 1 to this new directory.

(ie: path/to/formtools/mailchimp/MCAPI.class.php)


3) Add the MailChimp API code to your form.
I'm going to assume that you're using server-side (PHP) validation on your external form and that you already have a working form, so look for the following IF statement in your forms PHP:

PHP Code:
<?php
  
if (empty($errors))
  {
    
$params = array(
      
"submit_button" => "submit"// Change to name attribute of submit button
      
"next_page" => "http://www.yourdomain.com/thanks.php",
      
"form_data" => $_POST,
      
"namespace" => "you-should-do-this"// http://docs.formtools.org/api/?page=namespaces
      
"finalize" => true
    
);
    
ft_api_process_form($params);
  }
?>

Now you're going to add the following chunk of code just above the line with "$params = array("

Note: make sure you read all the comments in this code. Update fields to match your own form field name attributes. The following is just an example.

PHP Code:
<?php
    
// SUBSCRIBE TO MAILING LIST OPTION - ADD TO MAILCHIMP USING API
    
if (!empty($_POST['newsletter_input_name_attribute'])) 
    {
        
// Include Mailchimp API class
        
require_once('../formtools/mailchimp/MCAPI.class.php');

        
// Your API Key: http://admin.mailchimp.com/account/api/
        
$api = new MCAPI('Your-API-Key-Here');

        
// Your List Unique ID: http://admin.mailchimp.com/lists/ (Click "settings")
        
$list_id "Your-List-ID-Here";

        
// Variables in your form that match up to variables on your subscriber
        // list. You might have only a single 'name' field, no fields at all, or more
        // fields that you want to sync up.
        
$optinTIME date('Y-m-d H:i:s'); // Sample field - depends on your list, added 2013-08-22
        
$merge_vars = array(
            
'FNAME' => $_POST['first_name'],
            
'LNAME' => $_POST['last_name'],
            
'EMAIL' => $_POST['email_confirmation'],
            
'OPTIN_TIME' => $optinTIME//Added 2013-08-22
            
'OPTIN_IP' => $_SERVER['REMOTE_ADDR'//uses the user's IP address, but MC still says "you added this person"
        
);

        
// SUBSCRIBE TO LIST
        
if ( $api->listSubscribe($list_id$_POST['email_confirmation'], $merge_vars) === true ){
        
$mailchimp_result 'Success! Check your email to confirm sign up.';
        } else {
        
$mailchimp_result 'Error: ' $api->errorMessage;
        }
    }
?>

You're end result should look something like this:

PHP Code:
<?php
require_once("../formtools/global/api/api.php");
$fields ft_api_init_form_page(#, "live", "namespace");
$errors = array();
if (isset(
$_POST['submit']))
{
  
$rules = array();
  
$rules[] = "required,first_name,Please enter your FIRST NAME.";
  
$rules[] = "required,last_name,Please enter your LAST NAME.";
  
$rules[] = "required,address,Please enter your ADDRESS.";
  
$rules[] = "required,city,Please enter your CITY.";
  
$rules[] = "required,state,Please enter your STATE.";
  
$rules[] = "required,zip,Please enter your ZIP CODE.";
  
$rules[] = "required,phone,Please enter your PHONE NUMBER.";
  
$rules[] = "required,email,Please enter your EMAIL ADDRESS.";
  
$rules[] = "valid_email,email,Please enter a valid EMAIL ADDRESS.";
  
$rules[] = "required,email_confirmation,Please confirm your EMAIL ADDRESS.";
  
$rules[] = "valid_email,email_confirmation,Please enter a valid EMAIL ADDRESS.";
  
$rules[] = "same_as,email,email_confirmation,Please ensure the email addresses you entered are the same.";
  
$errors validate_fields($_POST$rules);
   
  
// no errors - great! Now we process the page. The ft_api_process_form does
  // the job of both updating the database and redirecting to the next page
  
if (empty($errors))
  {
    
// SUBSCRIBE TO MAILING LIST OPTION - ADD TO MAILCHIMP USING API
    
if (!empty($_POST['newsletter_input_name_attribute']))
    {
        
// Include Mailchimp API class
        
require_once('../formtools/mailchimp/MCAPI.class.php');

        
// Your API Key: http://admin.mailchimp.com/account/api/
        
$api = new MCAPI('Your-API-Key-Here');

        
// Your List Unique ID: http://admin.mailchimp.com/lists/ (Click "settings")
        
$list_id "Your-List-ID-Here";

        
// Variables in your form that match up to variables on your subscriber
        // list. You might have only a single 'name' field, no fields at all, or more
        // fields that you want to sync up.
        
$optinTIME date('Y-m-d H:i:s');
        
$merge_vars = array(
            
'FNAME' => $_POST['first_name'],
            
'LNAME' => $_POST['last_name'],
            
'EMAIL' => $_POST['email_confirmation'],
            
'OPTIN_TIME' => $optinTIME,
            
'OPTIN_IP' => $_SERVER['REMOTE_ADDR']
        );

        
// SUBSCRIBE TO LIST
        
if ( $api->listSubscribe($list_id$_POST['email_confirmation'], $merge_vars) === true ){
            
$mailchimp_result 'Success! Check your email to confirm sign up.';
        } else {
            
$mailchimp_result 'Error: ' $api->errorMessage;
        }
    }
  
    
$params = array(
      
"submit_button" => "submit_button_name_attribute",
      
"next_page" => "http://www.yourdomain.com/thanks.php",
      
"form_data" => $_POST,
      
"namespace" => "you-should-do-this",
      
"finalize" => true
    
);
    
ft_api_process_form($params);
  }
  
// it failed validation. Update $fields with the latest contents of the form data
  
else 
  {
    
$fields array_merge($_SESSION["namespace"], $_POST);
  }
}
?>


3a) Verify your merge tags are correct in MailChimp
Login to your Mailchimp account and view the list you want to use for this form. Select the Settings Menu and choose "List fields and *|MERGE|* tags". Verify that the tags are equal to your PHP code. (Eg: The "First Name" field label should have FNAME as the merge tag, if FNAME is in the PHP code).


4) Add your unique MailChimp API Key and List ID.
All that's left is to put in your own unique API key and List ID. Here are the instructions for finding those keys in your own MailChimp account:

Where can I find my API Key?: http://kb.mailchimp.com/article/where-ca...my-api-key

How can I find my List ID?: http://kb.mailchimp.com/article/how-can-...my-list-id

Keeping your API key secure.: http://kb.mailchimp.com/article/keeping-...key-secure


5) Test the new MailChimp integration.
You can test this out by submitting the live form with the proper input for "signing up" and then checking your MailChimp subscriber list to make sure you were added. If possible, I recommend using the double opt-in feature. It's just not something I coded, because it wasn't requested of my client at the time.


Resources:
- Add a Subscribe to MailChimp Newsletter Option on Your Contact Form in 5 Minutes:
http://www.joshuawinn.com/subscribe-to-m...tact-form/

- Official Example Code for MailChimp API v1.3 - listSubscribe() method:
http://apidocs.mailchimp.com/api/1.3/lis...e.func.php

- Example code for OPTIN_TIME provided by adamdehaven's answer:
http://stackoverflow.com/questions/15772...-mailchimp
Not a FT employee, just a FT user lending a hand. If I've been helpful, please rate.

[Image: giraffe_long_85.gif]
Reply
#2
Brandon,

This is awesome!! Thanks so much for posting this. We have numerous request from users on how to integrate with list management systems like MailChimp. I'm sure they will find this very helpful.

Cheers,

Joe
Reply
#3
I added some stuff today (see Updates at top). I will probably need to either create a duplicate thread or update this one in the coming months as Mailchimp is now using an entirely new API (2.0.2). Hopefully they don't EOL the 1.3.2 API anytime soon, because I really don't have time to re-learn everything (especially since I don't speak PHP very well).

Example: it took me ALL DAY to research, test and implement these changes for my own forms. Mostly because I'm not very good with PHP.
Not a FT employee, just a FT user lending a hand. If I've been helpful, please rate.

[Image: giraffe_long_85.gif]
Reply
#4
Awesome! Thanks so much for sharing!

Cheers,

Joe
Reply


Forum Jump:


Users browsing this thread: 1 Guest(s)