`.
-
------------------------
-Restricted HTML Content
------------------------
-
-The Bulk Course Email tool restricts use of specific HTML elements from being
-used in messages. The following HTML elements may not be used in messages
-authored with this tool:
-
-* iframe
-* svg
-* form
-* script
-
-.. note: If a message contains restricted HTML content it will **not** be
- stripped from the message. The HTML code will be converted to plain text. You
- should send a test message to yourself first before sending to larger groups
- to ensure message content is displayed as desired.
-
-======
-Images
-======
-
-Messages can include images. To include an image, you must first add the file
-to your course on the **Files & Uploads** page. For an email message, you copy
-the **Web** URL that the system assigns to the image. Then, in the email
-message editor, you select the **Insert/edit image** icon to add the web URL.
-
-.. note:: Scalable Vector Graphic (SVG) images are restricted from use in
- messages authored with the Bulk Course Email tool. Please see the above note
- in the *Restricted HTML Content* section.
-
-To ensure that your course assets are transmitted securely, add the
-``https://`` preface to the web URL. An example follows.
-
-::
-
- https://courses.edx.org/asset-v1:{course}.x+{run}+type@asset+block@{image}.jpg
-
-For more information, see :ref:`Add Files to a Course`.
-
-=========
-Keywords
-=========
-
-Messages can include variables that represent values that are specific to each
-message recipient, such as learner name or user ID. The LMS substitutes these
-variables, called keywords, with actual values when it sends a message.
-
-For more information, see :ref:`Use Keywords in Messages`.
-
-.. _Send_Bulk_Email:
-
-**************************************************
-Send an Email Message to Course Participants
-**************************************************
-
-.. Important:: You cannot cancel non-scheduled bulk email messages after you send them.
-
- Before you send a message to a wide audience, send the message only to
- yourself to test and review it. Make sure it displays as you intend it to,
- and that any links or media function correctly.
-
-To send an email message to course participants, follow these steps.
-
-#. View the live version of your course.
-
-#. Select **Instructor**, and then select **Email**.
-
-#. From the **Send to** option, select one or more groups of email recipients.
-
- .. note:: Make sure you understand who is included or excluded when you
- send a message to one, or a combination, of the recipient groups. For
- details, see :ref:`Bulk Email Who Is Included or Excluded`
-
-#. In the **Subject** field, enter a subject for the message.
-
-#. In the **Message** box, enter the text for the message.
-
- For details about options for composing your message, see
- :ref:`Options for Email Message Text`.
-
-#. Select **Send Email**. A bulk email task is queued for processing.
-
-Multiple courses use the same queue to complete these tasks, so it can take
-some time for your message to be sent to all of its recipients. You can
-perform other tasks on the instructor dashboard or navigate to other pages
-while you wait for your message to be sent.
-
-.. _Send_Scheduled_Bulk_Email:
-
-*********************************************************
-Send a Scheduled Email Message to Course Participants
-*********************************************************
-
-We have introduced a way to schedule a bulk email message to be sent at a
-specified date and time in the future. Once a message has been scheduled,
-and until the message has been sent, it will be possible to view, edit, or
-cancel these messages.
-
-.. Important:: Messages may not be sent at the *exact* time specified
-
- .. note:: We check the message schedules every fifteen minutes. For example,
- A message scheduled to be sent at 09:10:00 will not be processed until
- 09:15:00. Once the schedule for a message has elapsed it will be sent.
- When processed, these messages will be placed on the same queue that
- non-scheduled messages use, so it may take some time for your message to
- be sent to all recipients.
-
-To send a scheduled email message to course participants, follow these steps.
-
-#. View the live version of your course.
-
-#. Select **Instructor**, and then select **Email**.
-
-#. From the **Send to** option, select one or more groups of email recipients.
-
- .. note:: Make sure you understand who is included or excluded when you
- send a message to one, or a combination, of the recipient groups. For
- details, see :ref:`Bulk Email Who Is Included or Excluded`
-
-#. In the **Subject** field, enter a subject for the message.
-
-#. In the **Message** box, enter the text for the message.
-
- For details about options for composing your message, including using keywords to make the message more personal, see
- :ref:`Options for Email Message Text`.
-
-#. Check the **Schedule this email for a future date** checkbox. This also
- updates the **Send Email** button to a **Schedule Email** button.
-
-#. Enter a date (in the future) within the **Send date** field, or optionally
- click on the calendar icon to open up a date picker to assist in selecting a
- date for the message.
-
-#. Enter a time within the **Send time** field, or optionally
- click on the clock icon to open up a time picker.
-
-#. Select **Schedule Email**. A bulk email task is then scheduled for
- processing.
-
-=====================================
-Managing Scheduled Email Messages
-=====================================
-
-Once a message has been scheduled it will appear in the **Scheduled emails**
-table. Each entry will describe *when* the message will be sent (in local time),
-the *recipient groups* selected, the *subject* of the message, and the *author*
-of the message.
-
-.. image:: ../images/Bulk_email_scheduled_emails_table.png
- :alt: A tabular list of scheduled email messages, with columns for
- *send date*, *send to*, *subject*, *author*, and *action*.
-
-Each scheduled email entry in this table will support the following actions:
-
-* The *View* button will open a modal that allows you to view the contents of
- this message.
-* The *Delete* button will cancel the scheduled bulk email task and the message
- will **not** be sent. This sets the bulk email task's status to **REVOKED**.
-* The *Edit* button will allow you to edit the bulk email message. You will be
- able to adjust the recipients, subject, message contents, and/or the date and
- time the message should be sent.
-
-
-.. _Use Keywords in Messages:
-
-****************************
-Use Keywords in Messages
-****************************
-
-You can include keywords in your messages. A keyword is a variable: when you
-send the message, a value that is specific to the each recipient is substituted
-for the keyword. For example, when you use the ``%%USER_FULLNAME%%`` keyword,
-each message contains the name of the recipient.
-
-.. note::
- Do not use keywords in the Subject line of a message. The keyword in the
- subject will not be assigned a value, and the recipient will see the keyword
- text.
-
-===================
-Supported Keywords
-===================
-
-You can use the following keywords in your messages.
-
-* ``%%USER_ID%%`` - the anonymous user ID of the message recipient
-* ``%%USER_FULLNAME%%`` - the full name of the message recipient
-* ``%%COURSE_DISPLAY_NAME%%`` - the display name of the course
-* ``%%COURSE_END_DATE%%`` - the end date of the course
-
-===================
-Keyword Formatting
-===================
-
-You format keywords as: ``%%Keyword%%``. You can include keywords in any HTML
-tags in an email message. An example follows.
-
-::
-
- %%COURSE_DISPLAY_NAME%% Updates
-
- Dear %%USER_FULLNAME%%, this is a reminder that the last day of the course
- is %%COURSE_END_DATE%%
- . . .
-
-.. _Email_queuing:
-
-****************************
-Message Workflow States
-****************************
-
-When you select **Send Email** for a message, the server begins to process a
-bulk email task. The server assigns a series of different workflow states to
-the task.
-
-When you select **Schedule Email** for a message, the server creates a bulk
-email task and sets it to the **SCHEDULED** state. This task will remain in this
-state until it is ready to be processed.
-
-.. image:: ../images/Bulk_email_states.png
- :alt: Flowchart of the possible states of a bulk email task.
-
-Bulk email tasks can have the following workflow states.
-
-* Queuing: The bulk email task is created and being queued for background
- processing.
-* Pending: The task is queued and is waiting to run.
-* Scheduled: The task has been created and is scheduled to run at a future date
- and time.
-* Started: Background processing is in progress to create emailing subtasks.
-* Progress: The emailing subtasks are in progress.
-* Success: All emailing subtasks are complete. Note that the bulk email task
- can be in this state even if some or all of its emailing subtasks failed.
-* Failure: An error occurred and task processing did not complete successfully.
-* Revoked: The task was cancelled before it was processed.
-
-While the bulk email task is in progress, you can find out what stage it has
-reached in the workflow by checking the **Pending Tasks** section on the
-**Course Info** page of the Instructor Dashboard.
-
-.. image:: ../images/Bulk_email_pending.png
- :alt: Information about an email message, including who submitted it
- and when, in tabular format
-
-When the bulk email task is complete, you can find its final state by checking
-the Email Task History report. For more information, see :ref:`Email Task
-History Report`.
-
-.. _Review Sent Messages:
-
-********************************
-Review Sent Messages
-********************************
-
-You can review a list of all of the messages that have been sent for the
-course. For any listed message, you can review the subject, the username of the
-person who sent it, the date and time sent, its selected recipients, and the
-message text.
-
-#. View the live version of your course.
-
-#. Select **Instructor**, and then select **Email**.
-
-#. In the **Email Task History** section of the page, select **Show Sent Email
- History**. The list of sent messages displays.
-
-.. image:: ../images/Bulk_email_list.png
- :alt: A tabular list of sent messages, with columns for subject, sent by,
- time sent, and number sent.
-
-#. To review additional information for a sent message, select its subject. The
- message opens in a dialog box.
-
-.. image:: ../images/Bulk_email_sent.png
- :alt: A dialog box with the subject, sent by, date and time sent, sent to,
- and message for an email message, and an option to Copy Email
- to Editor.
-
-#. Optionally, use the message as the basis for a new message: select **Copy
- Email to Editor**. The dialog box closes and you can edit the text, links,
- and formatting that were duplicated into the **Subject** and **Message**
- fields.
-
- When you create a message by copying a previously-sent message, be sure to
- review and test it thoroughly before you send it to all course participants.
-
-.. _Email Task History Report:
-
-********************************
-Email Task History Report
-********************************
-
-The Email Task History report can help you keep track of who sent messages,
-when, to which groups, and how many messages were successfully sent. For each
-message sent, the report includes the username of the requester, the date and
-time it was submitted, the duration and state of the entire task, the task
-status, and the task progress.
-
-You can use this history to investigate questions relating to bulk email
-messages that have been sent, such as these examples.
-
-* How frequently learners are sent course-related email messages.
-* Whether a message was sent successfully.
-* The change in the number of people who were sent course-related messages over
- time.
-
-To produce the Email Task History report, follow these steps.
-
-#. View the live version of your course.
-
-#. Select **Instructor**, and then select **Email**.
-
-#. In the **Email Task History** section of the page, select **Show Email Task
- History**. A report like the following example displays on the instructor
- dashboard.
-
-.. image:: ../images/Bulk_email_history.png
- :alt: A tabular report with a row for each message sent and columns for
- requester, date and time submitted, duration, state, task status,
- and task progress.
-
-===========================
-Review Email Task History
-===========================
-
-For tasks with a **State** of Success, the **Task Progress** column shows an
-informational message. These messages can have a format such as "Message
-successfully emailed for 13457 recipients (skipping 29) (out of 13486)". To
-interpret this message, note that:
-
-* The first number ("recipients") indicates the number of messages sent to the
- selected recipients.
-
-* The second number ("skipping") indicates the number of enrolled and activated
- users who were not sent the message. This count is of learners who have opted
- not to receive course email messages.
-
-* The final number ("out of") indicates the number of users in the set of
- recipients you selected who were enrolled in the course (and had activated
- their user accounts) when you sent the email message.
-
-If the "recipients" and "out of" numbers are the same, the message reads
-"Message successfully emailed for 13457 recipients" instead.
-
-Other **Task Progress** messages for tasks with a **State** of Success indicate
-that some or all of the emailing subtasks did not successfully send email:
-
-* "Message emailed for {number succeeded} of {number attempted} recipients"
-* "Message failed to be emailed for any of {number attempted} recipients"
-* "Unable to find any recipients to be emailed"
-
-No **Task Progress** messages display for tasks that have a **State** of
-Failure.
-
-.. _Example Messages to Students:
-
-*********************************
-Example Messages to Learners
-*********************************
-
-You can use these example messages, prepared for delivery before typical course
-milestones, as models for your own course communications.
-
-.. contents::
- :local:
- :depth: 1
-
-These messages are styled as email messages, but you could also post this
-information in a course discussion topic or in a course update. To use
-:ref:`keywords