Product support

Get help in the plugin support forum.


Giveaways (or sweepstakes) is a powerful marketing tool. They allow you to drive traffic to your website and and attract new customers to your business. Giveaways are often faster and cheaper than other marketing channels. You can consider using a giveaway for many reasons:

  • Launching a new product or service. When you launch a new product or service you want to generate some buzz around the product and your brand. You can use your product as a giveaway prize, or use a high-value relevant product and then advertise your product to participants who don’t get the main prize.
  • Building an email list. Giveaways are a great for growing leads and building a targeted email list. You can spend just a hundred of dollars to build an email list of thousands of high quality email addresses. You can then promote your products to the subscribers, or upload the list to Facebook for retargeting, or create a lookalike Facebook audience to access even more potential customers.
  • Growing your audience or social following. Using giveaways you can expand your brand awareness and get your audience engaged with your business.
  • Driving traffic and sales. Run giveaways together with other marketing techniques on ongoing basis to gain a steady flow of visitors and convert them to customers.
  • Analyzing your audience. Giveaway participants are glad to share information in exchange for a chance to win. It’s a great opportunity to get some extra data about your audience. The plugin supports custom fields, so you can ask whatever you need.

There are many articles and tutorials explaining how you can use giveaways for a business. Check out these articles to learn more: How to Use a Giveaway to Accelerate the Growth of Your Email List - Neil Patel and Case study: List Growth: 11% increase from sweepstakes for current subscribers - MarketingSherpa.

Who can benefit from giveaways

Giveaways is an universal tool which work with any type of business in any industry:

  • Services and consulting businesses - grow brand awareness, build an audience, drive sales.
  • Businesses making digital products - grow awareness and audience, promote products, drive sales.
  • Brands selling physical goods - grow awareness and audience, promote products, drive sales.

Benefits of using the RainForest Giveaway plugin for October CMS

There are several platforms which offer giveaway hosting. Most of them are SaaS services, which require monthly subscriptions or payments for each giveaway. The subscription plans can be expensive, especially if you need a completely branded user experience and want to access all the features. And even the most expensive platforms do not give you the full control over the landing page. Also, the giveaway page is hosted on a third-party website, which doesn’t help with promoting your own website and domain name.

Giveaway plugin features:

  • Full white labeling - you can customize the giveaway page to match your brand style.
  • One-time payment - after purchasing the license you can run as many giveaways as you need.
  • Built-in analytics - see the conversion rate, visitors and participants for each day you run a giveaway.
  • Built-in virality - entrants are encouraged to share their Personal Giveaway URL in social networks to increase their chances to get the prize. Each time a new participant subscribes with a Personal URL, the URL owner gets one extra entry. The more entries a participant has, the more chances to win!
  • Compatible with popular email services - send follow-up emails to new participants to increase the engagement and remind them to share their personal Giveaway URL. MailChimp, Campaign Monitor and MailerLite are supported out of the box. Built-in welcome email is supported too, although it doesn’t provide any automation. https://bitbucket.org/alekseybobkov/giveaway-plugin-assets/raw/0f65649394672b83cc40f20cad1969e564f672f5/images/mail-services.png
  • Custom fields - you can add any number of custom fields to your Giveaway subscription form. The custom field values are exportable to CSV and are also sent to email services, so that you can use them in follow-up emails.
  • Export to CSV - you can export the list of participants to a CSV file for further processing, e.g. uploading to Facebook to create a custom or lookalike audience.
  • Responsive - the giveaway landing page is responsive by default. You can even upload two version of the title image - for the desktop and mobile layout. The @2x images are supported too.
  • Countdown timer - the countdown timer on the giveaway landing page creates the sense of urgency, which increases the conversion rate.
  • Integration with Bitly - the Personal Giveaway URL is shortened with Bitly to simplify the sharing process.
  • Customizable messages - the textual content for each giveaway landing page is customizable. You can change everything from the Submit button label to the Terms and Conditions text individually for each giveaway . * Built-in service abuse protection - the plugin does not allow a same participant to register multiple times. This is achieved with analyzing the email address, IP address and cookies.
  • Support for Open Graph tags - the built-in landing page implements Facebook Open Graph tags for better sharing experience.
  • Easy to use - the default landing page is included out of the box, and you can start using the plugin almost immediately if you don’t need heavy customization of your landing page.
  • Extensible - you can implement integration with email services which are not supported by default and handle API events when new participants subscribe.

Compatible with popular October CMS plugins

The plugin does not have any dependencies and does not require any other plugins to run. With that being said, you can use the plugin with any eCommerce or marketing plugins, for example:

Configuring the plugin

After installing the plugin, navigate to the Settings tab in the October CMS back-end and find the Giveaway plugin. Select default timezone you are going to run the giveaways in. Review and update the Terms and Conditions template.

Disclaimer: the included Terms and Conditions template is for informational purposes only and not for the purpose of providing legal advice.

The plugin requires a free Bitly account for shortening URLs. Follow these steps to sign up and obtain the API key:

  1. Navigate to the Bitly sign up page and create a free account.
  2. After confirming your email, click Generic Access Token in the sidebar menu on this page: https://bitly.com/a/oauth_apps. You can also access this menu by clicking the main menu icon in the right top corner of the page, and then clicking your account name in the sidebar menu.
  3. Enter your account password and click Generate Token.
  4. Copy the token and paste it to the Bitly token field on the Bitly tab on the Giveaway settings page.

Please note that Bitly doesn’t work with the localhost URI. If Bitly can’t shorten an URL, the plugin falls back to the long URL. You can find relevant error messages in the October CMS system log.

Using the built-in welcome email message

You can use the built-in welcome email message or extermail email services. The built-in message uses October CMS email system and does not provide email automation. You can find the email message template on the System / Mail templates page. The template code is rainforest.giveaway::mail.participant_confirmation.

In the template you can use the predefined shareUrl, unsubscribeUrl and title variables, as well as any custom variable you define in a giveaway configuration. See more about managing unsubscribed participants below.

Configuring integration with email services

The plugin has built-in support for MailChimp, Campaign Monitor and MailerLite services and can be extended with more services if needed. Read about implementing support for new email services on the Documentation tab.

When the plugin creates a new subscriber in an email service, it posts the following information:

  • Participant email address.
  • Values of custom fields you defined in the giveaway, if any.
  • Share URL variable. You should create a custom field with the corresponding name in your email service if you are going to provide the Share URL in your email templates. Each mailing service has its own rules for formatting the custom field names. The Giveaway plugin sends the Share URL under following names: SHARE_URL (this works with MailChimp), share_url (works with MailerLite), ShareURL (works with Campaign Monitor), shareurl, ShareURL and Shareurl.

To work with an external email service the following prerequisites are required:

  • The email service API key. Only one key is required to run any number of giveaways.
  • List or Group created in the email service, to collect subscribers. Each giveaway requires a separate List or Group.

Configuring MailChimp

  1. Sign into your MailChimp account.
  2. Create or copy the API key on the Account / Extras / API Keys page.
  3. Go to the October CMS Settings / Giveaway / Mailing Service tab, select MailChimp and paste the API key. Save the Settings.

For each new giveaway you will need to create a MailChimp List and bind it to the giveaway:

  1. In the MailChimp dashboard go to Lists and create a new List.
  2. Still in the MailChimp dashboard go to the list Settings / List Name and Defaults and copy the List ID.
  3. In October CMS - paste the List ID to the List identifier field on the MailChimp tab of the giveaway configuration page. Save the giveaway.

Configuring MailerLite

  1. Sign into your MailerLite account.
  2. Go to the Integrations / API page and copy the API key.
  3. Go to the October CMS Settings / Giveaway / Mailing Service tab, select MailerLite and paste the API key. Save the Settings.

For each new giveaway you will need to create a MailerLite Group and bind it to the giveaway:

  1. In the MailerLite dashboard go to Subscribers / Groups and create a new group for the new giveaway.
  2. Open Integrations / API page and copy the GroupID of the new group.
  3. In October CMS - paste the Group ID to the Group identifier field on the MailerLite tab of the the giveaway configuration page. Save the giveaway.

Configuring Campaign Monitor

  1. Sign into your Campaign Monitor account.
  2. Create or copy the API Key on the Account Settings / API Keys page. You need the API Key, not the Client ID.
  3. Go to the October CMS Settings / Giveaway / Mailing Service tab, select Campaign Monitor and paste the API key. Save the Settings.

For each new giveaway you will need to create a Campaign Monitor List and bind it to the giveaway:

  1. In the Campaign Monitor dashboard go to Lists & subscribers and create a new List for the giveaway.
  2. After creating the List, click Change name/type link on the List details page and copy the API Subscriber List ID string.
  3. In OctoberCMS - paste the List ID to the List identifier field on the Campaign Monitor tab of the the giveaway configuration page. Save the giveaway.

Important note: the Giveaway plugin sends ConsentToTrack flag to Campaign Monitor, indicating that Campaign Monitor is allowed to track email opens and link clicks. You may need to mention it in your Privacy Policy document.

Creating giveaways

After you configured the plugin and created the giveaway landing page (which is described in the Documentation section), the process of creating new giveaways is straightforward. Enter the giveaway title, description and images. All other configuration parameters have useful defaults, but you can change the default values.

Creating custom fields

For each giveaway you can create custom fields, which participant can fill out when they enter the giveaway. There are 3 types of fields: short text, long text and checkbox. For each field you can define whether the field is required.

Each field has the API Name configuration parameter. If you need custom field values to be associated with subscribers in your email service, you should create custom fields with the corresponding API names in that service. The API names are case sensitive. We suggest to create custom fields in your email service first, see which API names it creates, and then make fields with same names in the Giveaway plugin.

Picking a winner

For each giveaway you can pick one or multiple winners. The plugin does not send any notifications to winners. It is possible to cancel a winner selection and choose another winner, if needed.

To pick a winner, click the Pick a winner button on the GIveaway preview page. Enter a random number in the popup window and confirm the winner. Make sure the winner has not unsubscribed from your email service list (see below).

Managing unsubscribed participants

You should allow your participants to unsubscribe from the giveaway and any associated email notifications. There are two ways to achieve this:

  • If you use the built-in welcome email notification and don’t use and external email service, participants can click the Unsubscribe link in the email notification. The link will mark the participant as unsubscribed in the Giveaway dashboard. Unsubscribed participants are not visible in the Giveaway dashboard, although you can see the total number of unsubscribed participants. Unsubscribed participants are not exportable to CSV.
  • If you use an external email service, your participants can unsubscribe from the email list using the functionality provided by the email service. With this option the Giveaway plugin doesn’t show the unsubscribed participants count. The unsubscribed participants are still visible in the Giveaway dashboard, exportable to CSV and can be selected during the winner picking process. After picking a winner, make sure the participant has not unsubscribed from the email service. If it has unsubscribed, just choose another winner.

Abide by the law

Before you run a giveaway, make sure that you follow the laws of the country where you live. There are many articles and blog posts describing the regulations. For example:

In addition, all social networks have their own rules for advertising giveaways and contests.

Privacy Law

Collecting participant emails and other information may be a subject to the privacy law in your country. Make sure you follow the rules and that your Privacy Policy provides necessary details about how the information collected on the giveaway landing page is going to be used and shared with third parties. The Giveaway plugin creates cookies which do not contain any private information. They are encrypted and used only for session tracking purposes.

The plugin supports checkbox-type custom fields. You can make checkbox a mandatory field. This allows you to request a confirmation that a new participant is agree with your Terms and Conditions and Privacy Policy.

To create the giveaway landing page you must be familiar with creating layouts and pages in October CMS.

Creating the Giveaway page

The Giveaway plugin provides a fully implemented landing page. This includes the page markup, CSS and JavaScript code. The default markup uses Bootstrap 3 framework. It’s recommended that landing pages don’t have elements that can distract visitors from signing up, that’s why normally you don’t need to have your website menu or footer on the giveaway page. We choose Bootstrap 3 because it’s a well known framework and it provides enough flexibility for a landing page.

Create a new layout first, and call it “giveaway”, just for clarity. Paste the layout code from the snippet below:

description = "Basic giveaway layout"
<!DOCTYPE html>
<html lang="en">
        <meta charset="utf-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <title>{{ this.page.title }}</title>

        {% styles %}
        {% placeholder opengraph %}

        {% page %}

        <script src="{{ [
            ]|theme }}"
        {% scripts %}

If you need to use extra CSS styles on the giveaway page, add them below the closing HEAD tag.

Save the layout and create a new page. The page should use the layout you just created. Use this string for the page URL: /giveaway/:slug/:action?/:hash?. You can replace the giveaway segment in the URL if you need. With the default pattern you will have your giveaway landing pages available at /giveaway/giveaway-slug URL.

In the Components sidebar panel find the Giveaway component and drop it to the page code. This will create a single line of code:

{% component 'giveaway' %}

Save the page. Now you can create a test giveaway, enable it and open the giveaway page in the browser. If you used the default URL pattern, open /giveaway/your-giveaway-slug URL.

The Giveaway CMS component

The plugin installs a single CMS component called giveaway. The component has only one property - slug. By default its value is {{ :slug }}, which means that the value is loaded from the slug URL parameter. If you need, you can create pages highly customized for a specific giveaway. You can do it by creating a separate landing page and providing slug of a specific giveaway in the slug parameter. Then you can have giveaway page URLs like your-domain-name.com/win-the-product.

Customizing the giveaway page markup

If you are not happy with the default giveaway page markup, you can override the Giveaway component partials using the October CMS component partial overriding feature. You can find the original component partials in the plugins/rainforest/giveaway/components/giveaway directory. The mani component partial is default.htm, it contains references to other partials. Copy partials to the partials/giveaway/ directory in your theme and update them as you need.

Please note that the component includes a JavaScript file giveaway.js, which references some of the elements by their identifiers and uses data- attributes. Make sure to not remove those elements. However, you can completely replace the provided JavaScript file with your own.

Implementing integration with other email services

If you use an email service which is not supported by default, you can extend the plugin with a new service. This requires a new plugin. The plugin should:

  1. Define a class implementing RainForest\Giveaway\MailingServices\ServiceInterface interface.
  2. Register the new class by handling the rainforest.giveaway.mailing.listServices event.

The ServiceInterface interface has 3 methods, which describe the mailing service, define required form fields on the Create / Edit Giveaway page and handle new participants. Use plugins/rainforest/giveaway/mailservices/MailChimp.php or any other existing script from that directory as a reference.

To register your new registration class, define the boot method in the plugin registration class (http://octobercms.com/docs/plugin/registration) and add the event handler:

public function boot()
    Event::listen(['rainforest.giveaway.mailing.listServices'], function() {
        return [
            'YourAuthorName\YourPluginName\Classes\YourClassName' => 'Email Service Name'


Handling the new participant system event

The system triggers the rainforest.giveaway.participant.create event every time after a new participant is subscribed. You can handle the event if you need to implement integration with other services.

To handle the event, define the boot method in the plugin registration class and add the event handler:


public function boot()
    Event::listen(['rainforest.giveaway.participant.create'], function($participant, $giveaway) {
        traceLog(sprintf('Added new participant %s to giveaway %s', $participant->email, $giveaway->title));


The handler receives the giveaway and participant objects. The corresponding model classes are RainForest\Giveaway\Models\Giveaway and RainForest\Giveaway\Models\Participant.

To get a list of API names of all custom fields defined in a giveaway you can use getCustomFields() method of the $giveaway object. To get value of a custom field for a participant, call the getCustomFieldValue($fieldApiName) method of the $participant object.


Increased maximum length of the share link and Twitter message

Jul 12, 2018


Minor fix

Jul 12, 2018


Added winner column to the participants table

Jul 08, 2018


Added unsunscribed date column to the participants table

Jul 08, 2018


Added unsunscribe URL column to the participants table

Jul 08, 2018


Added mailing service configuration column to the giveaways table

Jul 08, 2018


Added custom fields column to the participants table

Jul 08, 2018


Added custom fields column to the giveaways table

Jul 08, 2018


Created visitors table

Jul 08, 2018


Added Twitter Text and Share Text giveaway columns

Jul 08, 2018


Added Cookie Id column to the participants table

Jul 08, 2018


Added Entry Has Closed text column

Jul 08, 2018


Added Form Title and Button Caption column

Jul 08, 2018


Added Use Default Terms and Conditions column

Jul 08, 2018


Added Published giveaway column

Jul 08, 2018


Initialization - created tables

Jul 08, 2018