Google has been enlightened enough to provide a GreaseMonkey API for Gmail; this message describes how I was able to use this same API from a Firefox toolbar authored using XUL.

The API provides methods and events that allow authors of Greasemonkey scripts to customize the GMail user experience. (See userscripts.org/tag/gmail for a number of useful GMail extensions.)

Because of security restrictions on the interactions allowed between trusted toolbar “chrome” and untrusted web pages, you’ll receive a scripting error if you attempt to simply call gmonkey.load() on the document object of the enclosed web page

Instead, I used the techniques described on developer.mozilla.org to allow the chrome and the webpage to interact. (If there’s a better/simpler way to make this work, please let me know!)

1. I used a "javascript:" URL to cause the gmonkey script to be loaded in the context of the GMail web page.

window.content.document.location =
"javascript:window.gmonkey.load('1.0', " + ML_GmailCallback + ")";

2. I dispatched a custom event to communicate information from the web page back out to the chrome:

foobar="something interesting";
var element = document.createElement("MyElement");
element.setAttribute("foobar", foobar);
document.documentElement.appendChild(element);

var evt = document.createEvent("HTMLEvents");
evt.initEvent("MyEvent", true, false);
element.dispatchEvent(evt);

3. I listened for this event in the chrome:

function ML_GmailListener(evt) {
    doSomethingCool(evt.target.getAttribute("foobar"));
}

doc.addEventListener("MyEvent", function(e)  { ML_GmailListener(e); },
    false, true);