======Email Campaigns======

=====Campaign Types=====

The typical process of creating business relationships is: **Lead > Opportunity > Account**

  * **Newsletter:** A recurring email campaign with predefined frequencies and predefined target list with options to subscribe and unsubscribe from a web portal.
  * **Email Campaign:** When you create an Email campaign, you can execute it through Sugar and view statistics to measure its success.
  * **Non-email based Campaign:** When you create other types of campaigns that cannot be executed through Sugar, such as Mail or Radio, you can create a record for your reference.

=====Create Target Lists and Targets=====

====Process====

The campaign process includes defining targets and target lists to direct the campaign to. Once you have determined your campaign criteria and who you want to target, then you will be ready to create a target list and then assign the targets to it. Usually, you create or import a target list first and then relate it to a campaign. However, you can also create a campaign first and then associate it with a target list.

====Definitions====

  * **Target:** An individual that you have some information on, but does not qualify as a lead or contact.
  * **Target List:** Multiple targets grouped together according to a set of predetermined criteria such as age group or spending habits.

While targets are stand-alone records that are not attached to contacts or leads, you can include contact, lead, target, and user records in a target list, as well as a combination of these types. Example: You may choose to target existing leads that need to be ‘nurtured’; run a report with lead criteria and import the report as a target list.

Note: Users can not ‘opt-out’, so they will not see the appropriate opt-out links in the email.

  * You can use a target list to specify individuals that you want to include in or exclude from a campaign.
  * You can add targets to the target list by selecting them from reports in Sugar.
  * You can also add targets to the target list by importing them from a file (either CSV or TSV) or by selecting them from existing contacts and leads.

====Target List Types====

When you create a target list, you can specify one of the following types:
  * **Default:** A list of people who are the campaign targets and receive the campaign email. Sugar performs a duplicate check to prevent duplicate emails being sent out to the Default list.
  * **Seed:** A list of people who need to receive the campaign email but must not be tracked as potential leads. Seed is primarily used for internal purposes, to confirm that the campaign has been successfully completed.
  * **Test:** A list of people who will receive a campaign email to test it before it is sent out to the default list. Test provides no duplicate check.
  * **Suppression List:** A list of people you want excluded from the campaign email recipient list. Suppression lists can be by ID, email address, or domain. Do not add suppression list for testing.
 
**Notes:**
  * Test and seed lists are ignored in email tracking statistics.
  * Users included on test and suppression lists will not receive the executed email.

====Creating a Target List====

  - From the Shortcuts section on the Campaigns Home page, click **Create Target List**.
  - On the Target Lists page, enter the target list information. See below.
    * **Name:** Enter a name for the target list.
    * **Type:** From the drop-down list, select the target list type. See Target List Types section above for details.
    * **Assigned to:** Enter the name of the user assigned to this list; click Select to select from the User list. By default, it is assigned to you.
    * **Team:** Enter the name of the team assigned to this list; click Select to select from the Team list. By default, it is assigned to you. Note: Teams are available in Sugar Professional and Sugar Enterprise.
    * **Description:** Enter a brief description of the target list.
  - Click **Save** to save the target list; click **Cancel** to exit the page without creating the list.

====Creating a Target====

This step is not necessary if you have already selected all of the targets you needed when you created the target list.

While you will generally purchase target lists and/or select targets from within Sugar, you can also manually create new target records. Targets are stand-alone records that are not attached to contacts or leads. If you plan to send email campaigns to existing contacts or leads, you will add them to your target lists.

  - On the Campaign Home page, in the Shortcuts section, click **Create Target**.
  - On the Targets page, enter information for the fields as needed. The majority of the fields are self explanatory. For information on some of the fields, see the fields below.
    * **Email Opt Out:** When you select this box, if the target clicks the “Unsubscribe” URL to opt-out of receiving your campaign emails, the system will display email address in the Opted Out sub-panel of the campaign’s Status page.
    * **Invalid Email:** When you select this box, if the email bounces back because the address was incorrect, the system will display it in the Bounced Messages, Invalid Email sub-panel of the campaign’s Status page.
    * **Do Not Call:** Select this box to add the target’s name to the Do Not Call list.
    * **Team:** Select the team that is allowed to view the account related to the target. Note: Teams are available in Sugar Professional and Sugar Enterprise.
  - Click **Save** to save the target list; click **Cancel** to exit the page without creating the list.

====Adding Targets to a Target List====

Once the target list record is created, you can add target, contact, lead, and user records to the target list.
 
From the appropriate sub-panel, click **Select** or **Select from Reports** to add the target records, which will appear in the sub-panel.
  * **Select:** A new window with the list view of the records appears. Select the appropriate records and click **Select**.
  * **Select from Reports:** A new window with the list of reports related to the record type appears. Select the appropriate report and click **Select**.

Note: Select from Reports is available in Sugar Professional and Sugar Enterprise.

=====Creating an Email Template=====

  - On the Campaign Home page, in the Shortcuts section, click **Create Email Template**.
  - Give the template a name, and fill in the other fields as needed.
  - To insert variables, select the value the variable should contain using the drop-down menus next to "Insert Varaibles," name the variable, and slick **Insert**. This will automatically insert the variable into the email body. You can also copy and paste the variable name into the subject field.
  - To add HTML to the page, click the **HTML** button in the top left of the "Body" editing window. A pop-up will open and allow you to add HTML code. Click **Update** in the pop-up window when finished with the HTML.
  - To insert an opt-out/unsubscribe link in HTML, add a paste the tracker URL from the Unsubscribe tracker (created in another stage). It should look something like: <a href="http://customer.consortiumservicesllc.com/ReverseProxy/SugarCRM_Consortium/index.php?entryPoint=removeme%26identifier={optout}">Unsubscribe</a>. For plain text emails, simply paste the full URL into the text. **It is important that the name inside the {} matches the name of the tracker!**
  - When finished, click **Save** at the top of the page.

=====Creating an Email Marketing Campaign=====

Creating an email marketing campaign through the wizard walks you through the steps for creating a campaign, adding budget, creating and linking tracker URLs and target lists, as well as defining the email to send out and executing the campaign.
 
**Note:** If you step outside the wizard prior to saving, you will lose your campaign data.

  - On the Campaign module, Actions section, select **Create Campaign (Wizard)**.
  - Select **Email** from the Campaign Type screen, then click **Start** to launch the wizard.
  - On the Campaign Header screen complete the fields described below to identify the campaign then click **Next**. Note: The Start Date, End Date, and Status values are for your records only. These values do not impact the execution of an email marketing campaign.
    * **Name:** Enter the campaign name.
    * **Status:** From the drop-down list, select the current status of the campaign. The status must be changed manually as the campaign progresses. Select from the following:
      * Planning: The campaign is in development and is not ready to execute.
      * Active: The campaign components are lined up and the campaign is ready to be executed.
      * Inactive: You do not want to execute the campaign at this time.
      * Complete: Once the results have been received, change the campaign status to complete.
      * In Queue: The campaign is waiting to be executed.
      * Sending: The campaign emails are in the process of being sent out when sending the emails out in several batches.
    * **Start Date:** Click the Calendar icon and select the date on which the campaign begins.
    * **End Date:** Click the Calendar icon and select the date on which the campaign ends.
    * **Assigned to:** Enter the name of the user assigned to the campaign; to choose a user from the Users list, click Select, and click the user name.
    * **Team:** Enter the name of the team that is allowed to view the campaign information; to choose a team from the Teams list, click Select, and click the team name. Note: Teams are available in Sugar Professional and Sugar Enterprise.
    * **Type:** The type selected in Step 2 above will appear, for email campaigns, email will appear.
    * **Description:** Enter a brief description of the campaign.
  - On the Campaign Budget screen enter budget and revenue details in order to track the campaign return on investment (ROI) as described below, then click **Next**.
    * **Budget:** Enter the budget for the campaign.
    * **Expected Revenue:** Enter the estimated revenue from the campaign.
    * **Currency:** Select the currency type for the campaign.
    * **Actual Cost:** Enter the actual cost incurred to conduct the campaign.
    * **Expected Cost:** Enter the estimated cost of the campaign.
    * **Impressions:** The number of people who opened the email.
    * **Objective:** Explain the goal of the campaign.
  - On the Campaign Tracker URLs screen, enter the tracker URL details in order to track the number of click-thrus for your campaign as described in the Campaign Tracker URLs Field/Description list below, then click **Next**.
    * **Tracker Name:** Enter a tracker name for your reference; use alpha-numeric characters. Example: Register Now!
    * **Tracker URL:** Enter the tracker URL and click Create Tracker. To create additional tracker URLs, click Create Tracker again. Example: http://www.sugarcrm.com.
    * **Opt-out Link:** Select this box to identify the tracker URL as an opt-out link and embed your “Unsubscribe” instructions in a tracker URL. By default, the system uses the removeme.php file which contains these instructions, and displays this file name in the Tracker URL field. Note: If you do not select the Opt-out link option, then the system inserts the default opt-out link. So, if you do not want to include an Opt-out link in your campaign message, select the Opt-out option but do not insert the link in the campaign message. Click the **Create Tracker** button for each tracker that you create, and click **Next** when finished.
  - On the Target Lists screen select or create target list(s) for use with your campaign. The target list(s) appears under the Target List Name below. Click either **Save and Continue** to move to the Marketing Email screen, or click **Finish** to view a summary of the campaign and enter the marketing email information at a later time.
    * To use an existing target list: click **Select.**
    * To create a new target list enter the name and type of target list and then click **Create**.
  - On the Marketing Email screen select or create the email template you will use to send to your target list(s) and complete the fields as described below. You can edit a previously created template to embed tracker URLs. Click **Next** to send the email.
    * **Name:** Enter a name for the marketing email.
    * **Use Mailbox:** From the drop-down list, select a mailbox that is set up for BounceHandling. The mail box name appears in the From Name field by default and can be changed. Note: This mailbox needs to be already set up by the Sugar Administrator.
    * **Status:** From the drop-down list, select Active if the record is in use; select Inactive if the record is not in use. Only active records will be queued for campaign launch. **Important:** Always set the status to Inactive while in development and testing. The status must be set to Active for the campaign to be executed.
    * **From Name:** Enter the name of the organization or person that is sending out the email.
    * **Start Date & Time:** Click the calendar icon and select a date to send out the email. Enter the time in the adjoining field. Note: To queue the email for campaign launch, select a date and time that has already passed; only after you ensure that the test email was successful.
    * **Email Template:** From the drop-down list, select an existing email template; to create a new template or edit an existing one, click the adjoining Create or Edit link respectively. Note: You will need to edit the template to add the Tracker URLs described in How Do I … Create Email Templates.
    * **Send This Message to:** Select one or more target lists from the box below; to send it to all the target lists in the box, select the All Target Lists in the Campaign box.
  - On the Send Email screen choose **Finish**, **Send Marketing Email As Test**, or **Schedule Email**, depending on whether you wish to send out a test, schedule your email to be sent, or simply to save your work and go to the summary. Click **Finish**. The campaign summary appears.
  - On the campaign summary screen you can edit the campaign, view the status and view the campaign return on investment.
  - In the Marketing Email section of the summary page you can send tests and schedule the email, as well as create a new marketing email to add to the campaign. Note: Prior to sending the email, run the campaign diagnostics. 

====Send Test Email====

To send the test emails, click the Send Test button above the detail view. **Important:** You MUST have a test target list for the test emails to be sent out.
    * Select the marketing email record you created above and click **Send**.
    * After a moment, the Status page appears with the messages sent.
    * 

====Execute the Campaign====

If you have multiple targets with the same email address, Sugar will send the campaign email to only one target, chosen at random. The other email addresses, considered duplicates, are suppressed.

To execute the campaign:
    * First change the email marketing record status to **Active**.
    * Then, click the **Send Emails** button above the detail view.
    * Select the marketing email record you created above and click **Send**.
    * After a moment, the Status page appears with the messages sent. The emails have now entered the Email Queue to be sent out according to their schedules.
    * Note: The start date, start time, and status selected in the email marketing screen determine when the email is sent.

====Duplicate Records====

There is no need to worry about duplicate records. While executing the email campaign, Sugar will automatically detect duplicate emails in the target list and will only send the email to one of them. The selection process is random.
====Manually Send All Emails in The Queue====

If you have emails in the queue, but you want them sent immediately, you can:

  - Log in as Administrator and click the **Admin** link in the top right corner of the page.
  - Scroll down to the "Email" section and click **Email Queue**.
  - You will see a table of currently queued emails. Click the **Send Queued Campaign Emails** button at the bottom of the table. This process can take a while.
  - If the emails do not, you may need to: select all emails you wish to send using the check boxes, click on **Actions** at the top of the table, click **Mass Update**, then at the bottom of the table change "In Process" from "-none-" to "No", and click **Update**.

=====Create and Embed Tracker URLs=====

====Link Types====

  * **Redirect links:** You can use one or more tracker URLs in your campaign emails to track the response to your campaign. The system generates a unique key for each URL and for each recipient and associates it with the email template. When recipients open the email and click on a URL link, the system, using the unique key identifier, tracks each action by each recipient.
  * **Unsubscribe Links:** Links can be included to allow targets to unsubscribe themselves from your campaign mailing list. You can embed an "Unsubscribe" link in a tracker URL. When targets click on this URL to unsubscribe from your campaign emails, the system logs the action for your records.
====Creating Tracker Redirect Links====

**IMPORTANT: The Tracker Name used in all email templates is "optout". Use this name!**

  - From the Campaign module, select the desired campaign.
  - On the Campaign detail page, scroll down to the Tracker URLs sub-panel, and click **Create**.
  - On the Campaign Trackers page, enter information for the fields as described in the Field/Description table below.
    * **Tracker Name:** Enter a tracker name for your reference; use alpha-numeric characters. This name is very important! This name is used when entering the tracker URL into an email template! The end of the URL will look like "identifier={optout}".
    * **Tracker URL:** Enter the tracker URL and click Create Tracker. To create additional tracker URLs, click Create Tracker again. Example: http://www.sugarcrm.com.
    * **Opt-out Link:** Select this box to identify the tracker URL as an opt-out link and embed your “Unsubscribe” instructions in a tracker URL. By default, the system uses the removeme.php file which contains these instructions, and displays this file name in the Tracker URL field. Note: If you do not select the Opt-out link option, then the system inserts the default opt-out link. So, if you do not want to include an Opt-out link in your campaign message, select the Opt-out option but do not insert the link in the campaign message.
  - Copy the full tracker URL to you clipboard so that it cam be pasted into your email template. The URL will usually start with http://127.0.0.1:80. This doesn't need to be changed, but it should be changed to the proper domain name when pasted into the email template.
  - To create the campaign tracker, click **Save**; click **Cancel** to exit the page without saving your changes. You can now insert this tracker URL into an email template of your choice.

=====Unsubscribe/Opt-Out Links=====

See **Creating Tracker Redirect Links** above.

=====Managing the Scheduler=====

====The Normal Way====
  - Log in as Administrator and click on the **Admin** link at the top right of the page.
  - Scroll down to the "System" section and click **Scheduler**.
  - Click on **Run Nightly Mass Email Campaigns**.
  - Click **Edit**.
  - Change settings according to your needs.
  - Use standard crontab notation for basic setup, or click the **Show Basic Options** link next to "Interval" to get a more user-friendly option selection.
  - Click **Save** when finished.
  - SugarCRM does not actually create a cron job, it must be created on the server manually. Log onto the CRM server as root and edit **/etc/crontab**. Add an entry identical to the cron settings in the Scheduler Settings page in Sugar. Enter: <code>0 * * * * www-data php5 /var/www/sugarcrm/cron.php</code> assuming that: you want it to run every hour on the hour, every day of the week, as the user www-data, using the php5 interpreter, and the cron script is located in /var/www/sugarcrm/. These are a lot of assumptions; adjust them as needed.
  - SugarCRM is finicky when it comes to the Scheduler. The settings in the Scheduler Settings page must match the crontab entry. Sometimes emails simply don't get sent, and it takes a log time to troubleshoot schedule problems. There is a better way.

====The Better Way====

  - Download the script **send_from_email_queue.py** from the SVN server at http://10.253.1.48/svn/SUGARCRM_AutoFormFill/
  - Place the script somewhere on the SugarCRM server. I placed it in the root of the CRM directory.
  - Put an entry in **/etc/crontab** similar to:<code>0 * * * * root python /path/to/send_from_email_queue.py</code> This is useful because it forces Sugar to send a batch of emails and ignores Sugar's schedule. More notes are located inside the script.
  - The size of the email batch is configured in Sugar under **Admin > Campaign Email Settings**.