How can I detect new kmails in a script?

So, Mafia will notify me of new kmails in the chat and gCLI. I'd like to detect and handle new kmails myself. But I can't figure out how to do it.

I thought it would be as simple as contains_text(visit_url("main.php"), "New message received"). But that never seems to return true - main.php never contains that text. Even when I receive a message, try that check (which returns false), then visit main.php in the relay browser, and I can see that text waiting there for me.

What silly mistake am I making? Is there an easier way to do this?

Try a chatbot script. It can respond to chat events, like a new message alert.

When KoL notifies you about stuff in chat, it does not also display it on main.php. What you are seeing there is mafia adding it to the main page, which only happens in the relay browser.

Bale, thanks for the chatbot tip. That will certainly come in handy for other things. But it's not exactly what I was hoping for here... What I'm really looking for is a one-time, on-demand check for messages, not an always-on listener. Specifically, I'm hoping to check for messages in my login script, but I don't really want to repeat that same check the entire time I'm logged in. I suppose I could enable and then disable a chatbot script by modifying the chatbotScript property, but that seems gross.

lostcalpolydude, I figured that the main.php notification might be inserted by Mafia. But when I receive a kmail when I'm logged out, then log in to native KoL (without Mafia), one of the frames does include the string "New message received from <a target=mainpane href='showplayer.php?who="... How can it be that this is visible in native KoL, but not by visit_url()? Is Mafia subtracting this text from main.php as a part of its own notification? I'm confused.

KoL requires visiting main.php for a lot of reasons before you can do anything else. Because of that, and because plenty of people never open the relay browser, KoLmafia loads main.php before checking anything about your character state. (With that resolved, KoL won't even let you adventure without loading main.php first.) That means the notification is gone by the time your script runs.

You might be interested in messages.php?events=1. But then you still have to filter out old notifications. At that point, just load messages.php.

What you could really do is load api.php?what=messages&since=[value that you remember from your last check, documented if you just visit api.php]&for=[read the doc].

It really depends what end goal you're going for.

Okay, that makes sense. So I tried
visit_url("api.php?what=messages&since=11/13/15&for=paladinwhitecheckkmails")
... but all I get is the api.php documentation. I think maybe I should be using what=events instead, (then using what=kmails&id=[] to read them), but that also doesn't work.

Visiting api.php gives some explanation of what to use for "since", at least enough to indicate that what you tried isn't what you need.

api.php says "retrieve all events after this date/time (parseable by strtotime())"

The linked http://us3.php.net/strtotime says "The function expects to be given a string containing an English date format..." It links to http://us3.php.net/manual/en/datetime.formats.date.php, which gives examples of "American month, day and year" as "12/22/78", "1/17/2006", "1/17/6".

The linked http://us3.php.net/manual/en/datetime.formats.compound.php also gives a valid "Unix Timestamp" example as "@1215282385". But visit_url("api.php?what=messages&since=@1447531139&for=paladinwhitecheckkmails") also just gives me the API documentation.

I did read the documentation. Honestly, I did. From what I can tell, either the documentation is wrong, or KoL is implementing this function in a way that makes at least some of the documentation misleading.

Or, I'm missing something simple, but I think that thing must be a typo or a formatting error - not an error in overall understanding. I'm all for "teach a man to fish," but if someone would be willing to give me an example of a workable since= value as a jumping-off point, it would be much appreciated.

(Ideally, I'd like to be using a since= value that includes date and time. But I thought I'd start with the simpler option, and got nowhere.)

Sorry, I'm the one that failed to read the documentation properly. The since section says it's for events, making my previous posts pointless.

You could just load messages.php and look for the blue New text, but then it won't be there when you go to actually read the kmails.

There's the CLI command events to show the list of things mafia shows on the main page. There doesn't seem to be an ASH equivalent.

Thanks. I never noticed the "New!" tag in messages.php. This works perfectly in my login script. (I'm not looking for anything more complicated than an alert that there is, in fact, a new message.)

contains_text(visit_url("messages.php"), "<span style="color:blue;">New!</span>")

For reference of anyone else who ends up here, visit_url("api.php?what=events&since11/11/15&for=X") does return a list of green chat events, including kmail IDs, in chunks of 100. So that's an avenue to accessing the message directly.

fyi, zarqon's zlib has some code that loads kmail from your inbox using api.php. You may want to take a look at that and/or appropriate that code (load_kmail, I think it is?).

Thanks - I'll definitely take a look.