--- name: canvas-inbox-messaging description: Use when an instructor wants to browse Canvas courses, select students by grades or activity, draft personalized Inbox messages with direct course links, approve recipients, and send individual messages. --- # Canvas Inbox messaging Use the `canvas-inbox` tools for live Canvas data and sending. The Instructure documentation MCP server is for API reference only; it cannot access student data or send messages. Follow these five stages in order. Ask one stage's main question at a time. Use details the teacher has already supplied rather than asking them to repeat themselves, while still obtaining the two separate approvals below. Explain choices in ordinary language; tool names, confirmation strings, and JSON are internal details. 1. **Choose courses.** At the start of a new messaging task, call `get_course_scope` and `list_available_courses`. Show a numbered list or table with course name, exact course code (e.g. SPAN101), Canvas course ID (e.g. 76), selected status, and supplied dates. Ask “Which course or courses should we use?” Accept list numbers, codes, names, or IDs, resolving them to the displayed entries. A numeric reference may be a Canvas ID rather than a code; clarify only if ambiguous. Call `configure_course_codes` with the chosen entries' exact `course_codes` and `course_ids`. Never select all courses automatically or silently reuse a saved scope for a new task. Configuring the full desired set replaces the previous set and invalidates student lists and message previews. 2. **Describe conditions.** Ask “Which students do you want to message? You can describe the conditions in your own words.” Translate natural language such as “below 70%,” “above 90% on the midterm,” or “haven't logged in this week” into supported grade and/or activity criteria. Resolve assignment references with `list_assignments`. Clarify course versus assignment grade, thresholds, all versus any conditions, ambiguous date boundaries, and whether never-active students should be included when needed. Explain that Canvas supplies recorded course activity, not a verified login. For “this week,” clarify the intended week boundary if absent and use the teacher's timezone to compute `inactive_since.since` as an ISO timestamp with timezone. For “past seven days,” use `inactive_for_days.days: 7`. Show the exact interpretation with the recipient list. Course grades use current/final percentage; assignment grades use posted score / possible points. Do not invent unavailable criteria or collect message text at this stage. 3. **Review and approve students.** Call `preview_recipients` for each chosen course using that course's conditions. Retrieve every remaining page with `get_recipient_list`; present all matching student names grouped by course, counts, interpreted conditions, and missing-data counts. Never describe a partial sample as the complete list. Ask “Do you approve this student list?” Wait for explicit approval, then call `approve_recipient_list` for each approved list ID. If conditions change, create and display a new list and obtain approval again. If there are no matches, help revise the conditions. Lists expire after 30 minutes; an expired or replaced list requires a fresh review and approval. Do not ask for the message until the teacher has approved the audience. 4. **Write the message.** Ask “What would you like the message to say? I can help draft it.” Obtain or help draft a subject and message, using `{{first_name}}` or `{{full_name}}` for individual greetings. Reuse message text already provided by the teacher. Avoid inserting sensitive details unless requested and supported. Call `preview_message` with each approved `recipient_list_id`, subject, and body template. This uses the exact approved audience without rerunning the selection. For multiple courses, preview each course's message and retain all preview IDs. 5. **Approve and send.** Show the subject, a personalized example, intended courses, and exact recipient counts. Ask “Do you approve sending this message to these students?” Wait for explicit approval of this final message preview; approval of the student list alone does not authorize sending. Revisions require a new message preview and final approval. Only then call `send_preview` with each preview ID and its exact returned `confirmation`. Continue approved batches of up to 20 students until each returns `complete` or `stopped`. Report sent and uncertain counts by course. If sending stops partway, ask the teacher to check the uncertain case in Canvas before any new preview. Do not claim complete delivery when a send is incomplete. The sender is the instructor authenticated by the Canvas token. The server sends one `POST /api/v1/conversations` request per student with exactly one recipient and a rendered personal greeting; it never creates a group conversation. Canvas may reuse an existing private conversation with that student. During message drafting (stage 4), offer course links when relevant or requested: “What should the message say, and would you like links to any course items?” Use `list_course_links` on the audience's selected course to search for pages, assignments, quizzes, and discussions by title or ID. If multiple items match, show their titles and types and ask which one the teacher means. Use the returned `type` and `id` exactly: a page ID here is its URL slug; New Quizzes appear as assignment references with `quiz_engine: new`. Never invent links or copy an item ID from one course into another. If a category is unavailable, report it rather than claiming there are no items. Follow `next_offset` when more results are needed. Pass chosen references in `preview_message.course_links`, each with a unique simple key such as `study_guide`, returned type/ID, and optional teacher-chosen label. Put `{{link:study_guide}}` where that link belongs in the body, or omit the placeholder to append it under “Course links.” The server fetches the item again and checks that it is published and belongs to the audience course. Use titles and full URLs in the actual message body; HTML/Markdown link rendering is not guaranteed by the Conversations API. Do not tell the teacher raw URLs are hidden behind clickable labels. In chat, you may show the same destinations as normal clickable Markdown links, while making the actual message text clear. Include every selected link's title and destination in the final approval preview. Changing links requires a new message preview and send approval. For multiple courses, look up and preview the intended item separately in each course; do not assume matching titles mean matching IDs or URLs. Never silently drop a requested link that cannot be resolved. Published status is not proof that each student can open an item; dates, prerequisites, and differentiated assignments may still restrict access. Do not change course publication or student access while preparing messages. Course discovery uses Canvas's active teacher enrollment and available course status. Canvas may still return older courses or sandboxes with those statuses. Include supplied start/end dates in the choices, especially an end date in the past, so the instructor can identify their intended courses. Do not describe these API statuses as proof of a current academic term.