Attaching labels to messages in Gmail via IMAP using code

concerning Gmail labels - what are they technically speaking. I mean through imap connection I can access a gmail mailbox and go through the emails however let say I wish to create a label and attach it to the emails as I loop through them using code - how can I do that in code? I'm using php - and Zend Framework.

EDIT ===

Thanks for the replies so its now clear that labels are treated like folders in this respect however I've tried the Zend_Mail_Storage_Imap class functions with interesting results. If I try the Zend_Mail_Storage_Imap:moveMessage function - it removes the message from wherever it is and literally attaches a label to it meaning if I wish to attach a label foo to my message it removes it form the inbox and attaches the label foo. However if I use Zend_Mail_Storage_Imap::copyMessage that does the trick.

However I'm wondering here that doesn't this literally make a duplicate copy of the message and you end up with more than one duplicate message right here?

Also what if I need to select all the messages that are attached with a certain label or in this case within a certain folder?

Re: concerning Gmail labels - what are they technically speaking.

Since IMAP doesn't have the concept of "labels", there is a mapping, more or less, between GMail "labels" and IMAP "folders" Here is the best doc I found on it. But what really helped me in creating my programmatic IMAP interaction with GMail was experimentation.

For example, the preset labels have IMAP folder names of

Human name -- IMAP Folder name
Drafts -- [Gmail]/Drafts
Sent Mail -- [Gmail]/Sent Mail
Spam -- [Gmail]/Spam
Starred -- [Gmail]/Starred
Trash -- [Gmail]/Trash

Added--

Re: create a label and attach it to the emails as I loop through them using code - how can I do that in code?

To create a label, use the Imap 'create folder' operation.

Use the Imap copy operation to add a label to a message.

To remove the message from the GMail Inbox, I am 90% sure that you add the IMAP Flag 'Deleted'. -- But please experiment with this first. It is not clear to me which label(s) are removed when you set the deleted flag. In my tests, the message only had 1 label (Inbox) when I applied the deleted flag.

Here is the code I use for moving a GMail message from Inbox to the Trash folder:

# Ruby code...
imap.store(message_id, "+FLAGS", [:Deleted]) # rm inbox label
imap.copy(message_id, "[Gmail]/Trash")       # add trash label

For PHP have you tried imap_mail_move?

http://ro.php.net/manual/en/function.imap-mail-move.php

Gmail supports storing of labels on a per message basis:

a011 STORE 1 +X-GM-LABELS (foo)
* 1 FETCH (X-GM-LABELS (\Inbox \Sent Important "Muy Importante" foo))
a011 OK STORE (Success)

From their API Tools site: http://code.google.com/apis/gmail/imap/#x-gm-labels

I'm very late to the party here, but people might find this information from https://developers.google.com/gmail/imap_extensions useful:

Gmail treats labels as folders for the purposes of IMAP. As such, labels can be modified using the standard IMAP commands, CREATE, RENAME, and DELETE, that act on folders. System labels, which are labels created by Gmail, are reserved and prefixed by "[Gmail]" or "[GoogleMail]" in the list of labels. Use the XLIST command to get the entire list of labels for a mailbox.

The labels for a given message may be retrieved by using the X-GM-LABELS attribute with the FETCH command. The attribute is returned as a list of ASTRINGs, encoded in UTF-7 as appropriate. An ASTRING is an atom or a string as defined by the RFC.

The following is an example transcript of a call to retrieve the X-GM-LABELS of several messages with the FETCH command:

a010 FETCH 1:4 (X-GM-LABELS)
* 1 FETCH (X-GM-LABELS (\Inbox \Sent Important "Muy Importante"))
* 2 FETCH (X-GM-LABELS (foo))
* 3 FETCH (X-GM-LABELS ())
* 4 FETCH (X-GM-LABELS (\Drafts))
a010 OK FETCH (Success)

Labels may be added to a message using the STORE command in conjunction with the X-GM-LABELS attribute. The following is an example transcript demonstrating the addition of a label to a message:

a011 STORE 1 +X-GM-LABELS (foo)
* 1 FETCH (X-GM-LABELS (\Inbox \Sent Important "Muy Importante" foo))
a011 OK STORE (Success)

The X-GM-LABELS attribute may also be used in the SEARCH or UID SEARCH commands to find the sequence numbers or UIDs of all messages in the folder with a given label. The following is an example transcript of a call to retrieve the sequence numbers of several messages using the SEARCH command:

a012 SEARCH X-GM-LABELS foo
* SEARCH 1 2
a012 OK SEARCH (Success)