MailChimp Integration Guide


Almost all elections are accompanied with an email campaign. One to announce the start of the election, and perhaps one or two reminders sent while voting is underway to those who have not voted. For elections fully hosted on the ElectionsOnline website (as opposed to partially or fully integrated into a client’s own website) those emails may be sent by ElectionsOnline but the only reporting that comes with that is a report showing the non-delivered emails. To get robust delivery and engagement reporting, clients may opt to use a dedicated email marketing tool where they will also have total control over the content and branding of their emails.

What the integration does

The integration makes it possible to flag a list subscriber’s record in MailChimp as having voted once they have submitted a ballot at ElectionsOnline. This in turn makes it possible to know who hasn’t yet voted and should receive an email reminder to do so. It should be noted this integration is only possible with elections fully hosted at ElectionsOnline. For elections that are partially or fully integrated into a client’s website, the ElectionsOnline system keeps the underlying voter repository (an AMS for example) up to date. It would then be up to the client to keep that synchronized with MailChimp should clients wish to eliminate the task of manually updating a list before sending a mailing.

Be aware that ElectionsOnline communicates with MailChimp hourly to set a voter’s voting status to Yes rather than at the exact instant a ballot is cast. Detaching the synchronization process from the process of casting a ballot ensures there will be no interference with casting ballots at times when the connection to MailChimp is degraded or unavailable due to regular maintenance.

Making ElectionsOnline and MailChimp work together

No technical skills are required to set up an integration between MailChimp and ElectionsOnline, but these instructions do make the following assumptions:

Special note about election configuration

Even though the point of this integration is to use MailChimp to send announcements and reminders, you must still include email addresses (when available) in the voter roster loaded into ElectionsOnline for two reasons:

Because you will be using MailChimp to send the announcement email and any reminders, make certain to instruct ElectionsOnline to not send these mailings. In other words:

Load your subscriber list into MailChimp

  1. Prepare your subscriber list in a spreadsheet with at least the following columns.
    Column name Value
    Email Subscriber’s email
    Voted “No” (Assign “No” as the default value for all voters. The integration will change this to “Yes” when a person votes.)
    Note: Email and voted are mandatory in order for the integration to work, but you may include as many additional columns as you like and will likely want to include first name and last name to be able to personalize the greeting of each email. If you have other personalization fields you wish to include in the email, include them as separate columns in the spreadsheet as you would for any mailing. Also, if you wish to notify voters of their username and password by email, you will need to include those columns.
    A typical spreadsheet will have a column structure similar to the following.
    FirstName LastName Email Voted Username Password
    Edwardo Castro No Castro 3jsh9k3q
    Kathy Chandler No Chandler s93js7d1
    John Cleveland No Cleveland yjhsb3is
    Janet Collier No Collier 2jsh87sc
    Abigail Cookey No cookey s7s3hsns

  2. Load the list into MailChimp and provide it a meaningful name. For example, if this is your General Election, name the list General Election. For smaller chapter elections, name it accordingly.
  3. MailChimp will treat the voted column as a merge field and generate a name for it that is only meaningful for the MailChimp system’s own internal reference. This is the field the ElectionsOnline integration will act on and change to Yes when a person votes, so you must give it a name that is meaningful to ElectionsOnline. In your MailChimp account:
    1. Click Lists in the navigation.
    2. Click the list you just created.
    3. Under the Settings option, click List fields and *|MERGE|* tags.
    4. Under the Field label and type column, find the row with the value voted. (See the image below.)
    5. For the row identified in the step above, go under the column labeled Put this tag in your content: change the value of the field to VOTED. This permits ElectionsOnline to identify this field through the integration. (See the image below.)
    6. For the voted field, check required and provide a default value of No. This is a good practice in the event a new subscriber is added to the list as the election is underway and ensures they have the proper default values. (See the image below.)

Prepare your campaign

  1. Prepare a mailing as you normally would in MailChimp. Remember that if this election uses a username and password intended for one-time use on this election, you will probably wish to include that directly in the body of the email so take care to include the appropriate merge fields in your email.
  2. Click the Campaign option in the navigation, then click the campaign name you created in step one.
  3. On the Who are you sending to? screen, click Group or new segment and select to send only to subscribers where voted = No as shown in the image below.

Note: ElectionsOnline will update the voted column to Yes as people vote. Configuring your campaign to only send to subscribers where voted = no ensures announcements and reminders are not sent to those who’ve already voted.

Connect MailChimp to ElectionsOnline

Provide ElectionsOnline with a MailChimp API key.

  1. In your MailChimp account go to Account under the username.
  2. Under the Extras menu, click API Keys. Even if you’ve already created an API key for some other use, click Create a Key to generate a new one just for ElectionsOnline.
    Note: API keys may be disabled, and it’s good practice to keep your ElectionsOnline API key enabled only so long as it’s in use. That means once your election concludes, you may wish to come back to this page and disable it. If your election is an annual event, you can always re-enable the key when it comes time to use it the following year. For organizations that conduct elections year-round, leaving the key always enabled is preferable.
  3. Under the Label column on this page, click the label box. This makes the label editable and type ElectionsOnline. When you have multiple API keys, this will help you easily recognize which key is used for which purpose.
  4. Copy the newly-created API key.
  5. In your ElectionsOnline account, click the Integration Settings link associated with any election you have created.
  6. In the MailChimp API Key field, paste the API key copied from MailChimp, then click Save.
    Note: You will only need to provide ElectionsOnline with your API key once as it is stored for reuse on future elections, but you may update it with a new key at any time.

Provide ElectionsOnline with your MailChimp list ID.

Each list in MailChimp has a distinct ID. For each election, you will need to provide that list ID to ElectionsOnline.

  1. Click Lists in the MailChimp navigation.
  2. Click the list you wish to associate with a specific election.
  3. Under Settings, click List name and defaults.
  4. This page shows your List ID. Copy that ID.
  5. In your ElectionsOnline account, click Integration Settings for the election you wish to associate with this list.
  6. Paste the MailChimp list ID into the MailChimp List ID field and click Save. Your integration setup is now complete.