Integrating A MailChimp Newsletter Option

[michatmaster7]

.
.

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

[Joe]

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

[michatmaster7]

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.

[Joe]

Awesome! Thanks so much for sharing!

Cheers,

Joe

[Makayla Lardner]

To sending email in bulk you must need the best tool which name is mail champ and it gives the free bulk email to send in one time. So you must check the essaygeeks review so that it will mike you more happy and active.

[Jacob Picton]

Whenever you try to open new site or forum, you have to fill up the form that is the basic requirement. Although I suggest that vape shops in lahore will guide you according to your needs and demands as well.

[Macejkovic]

Tony alien is implied for the struggle and all tips for the factors. All the joys of the tony and Nals certification medical in the simple methods for the guys. The base is counted for the approval of the target for the terms and themes.