forward_email

Instructions

Implementation Reference

• src/productivity_mcp/server.py:265-277 (handler)

  The `forward_email` MCP tool handler. It is decorated with @mcp.tool() and @_logged, accepts a message_id, recipients (to), optional body, account, folder, and html flag, then delegates to the email provider's forward_message method.

  @mcp.tool()
  @_logged
  def forward_email(
      message_id: str,
      to: list[str],
      body: str = "",
      account: str | None = None,
      folder: str = "INBOX",
      html: bool = False,
  ) -> dict[str, str]:
      """Forward an email to new recipients, optionally prepending a note."""
      mid = _email(account).forward_message(message_id, to, body=body, folder=folder, html=html)
      return {"message_id": mid}

• src/productivity_mcp/providers/base.py:98-106 (schema)

  Abstract interface for forward_message in the EmailProvider base class, defining the contract: message_id, to list, optional body/folder/html, returning the new message ID string.

  @abstractmethod
  def forward_message(
      self,
      message_id: str,
      to: list[str],
      body: str = "",
      folder: str = "INBOX",
      html: bool = False,
  ) -> str: ...

• src/productivity_mcp/providers/gmail_email.py:190-208 (helper)

  Gmail implementation of forward_message. Retrieves the original message, prepends 'Fwd:' to the subject if not already present, builds a combined body with the original message quoted under a 'Forwarded message' header, and sends via the Gmail API's send_message.

  def forward_message(
      self,
      message_id: str,
      to: list[str],
      body: str = "",
      folder: str = "INBOX",
      html: bool = False,
  ) -> str:
      original = self.get_message(message_id, folder=folder)
      subject = original.subject if original.subject.lower().startswith("fwd:") else f"Fwd: {original.subject}"
      combined = (
          f"{body}\n\n---------- Forwarded message ----------\n"
          f"From: {original.sender}\n"
          f"Date: {original.date}\n"
          f"Subject: {original.subject}\n"
          f"To: {', '.join(original.recipients)}\n\n"
          f"{original.body or ''}"
      )
      return self.send_message(to=to, subject=subject, body=combined, html=html)

• src/productivity_mcp/providers/imap_email.py:191-209 (helper)

  IMAP implementation of forward_message. Same logic as Gmail variant: fetches original, prepends 'Fwd:' to subject if needed, quotes original message in body, and sends via the IMAP provider's send_message.

  def forward_message(
      self,
      message_id: str,
      to: list[str],
      body: str = "",
      folder: str = "INBOX",
      html: bool = False,
  ) -> str:
      original = self.get_message(message_id, folder=folder)
      subject = original.subject if original.subject.lower().startswith("fwd:") else f"Fwd: {original.subject}"
      combined = (
          f"{body}\n\n---------- Forwarded message ----------\n"
          f"From: {original.sender}\n"
          f"Date: {original.date}\n"
          f"Subject: {original.subject}\n"
          f"To: {', '.join(original.recipients)}\n\n"
          f"{original.body or ''}"
      )
      return self.send_message(to=to, subject=subject, body=combined, html=html)

• src/productivity_mcp/util/rate_limit.py:17-30 (registration)

  Rate limit registration for forward_email: 20 calls per 60-second window, enforced by the @_logged decorator via the RateLimiter.

  _DEFAULT_LIMITS: dict[str, tuple[int, float]] = {
      # tool_name: (max_calls, window_seconds)
      "send_email": (20, 60.0),
      "send_draft": (20, 60.0),
      "reply_email": (20, 60.0),
      "forward_email": (20, 60.0),
      "delete_email": (50, 60.0),
      "delete_event": (20, 60.0),
      "bulk_set_read": (10, 60.0),
      "bulk_delete_emails": (10, 60.0),
      "bulk_move_emails": (10, 60.0),
      "create_event": (30, 60.0),
      "update_event": (30, 60.0),
  }