gmail.py - interact with Gmail through python

• gmail.py wraps imaplib and smtplib to make it easier to interact with your Gmail account through python.

• Examples:

  • Login (this automatically connects to IMAP and SMTP) and then out:

    import gmail conn = gmail.Gmail('username', 'password')

    do stuff...

    conn.logout()

  • Interact with labels:

    conn.labels.switch('sent') 1567 # Number of emails in that label conn.labels.create('mylabel') conn.labels.delete('mylabel') conn.labels.exists('foo') False len(conn.labels.all()) 25

  • Search email:

    Chainable queries

    conn.search.subject('foo').to('[email protected]') conn.search.unread() msgs = conn.search.all()

    msgs will be unread emails sent to '[email protected]'

    with 'foo' in the subject

  • Download email:

    msgs = conn.search.unread().all() msgs [<gmail.Message object...] msgs[0].subject() 'V1agra for Sale! #1 ONLINE PHARMACY!' msgs = conn.all()

  • Send email:

    msg = gmail.Message().fill('[email protected]', '[email protected]', ... 'fwd: fwd: funny', 'pictures of cats') msg.to_addresses() ['[email protected]'] msg.subject() 'fwd: fwd: funny' conn.send(msg)

• Notes:

  • Messages are not downloaded when they are created. They store their id and a reference to your IMAP connection. When you first try to read anything from them, they download.

  • Basically zero error handling is done right now.

• API (no return unless indicated):

  Gmail.init(username, password)

  • Connect and login to Gmail.
  • The current label is set to the inbox.
  • Returns a Gmail object.

  Gmail.logout(close_imap=True, close_smtp=True)

  • Close connections.

  Gmail.fetch(id)

  • Return a Message object for a given id.

  Gmail.send(message)

  • Send a Message object.

  Gmail.search.clear()

  • Clear the current query.

  Gmail.search.first()

  • Returns the first Message result for the current query.

  Gmail.search.all()

  • If a query is in progress, returns a list of result Messages.
  • Otherwise returns a list of all Messages for the current Label.

  Gmail.search.count()

  • Returns the number of results for the current query.

  Gmail.search.unread() Gmail.search.read() Gmail.search.to(query) Gmail.search.from_(query) Gmail.search.subject(query) Gmail.search.bcc(query) Gmail.search.cc(query) Gmail.search.body(query) Gmail.search.since(date) Gmail.search.before(date) Gmail.search.on(date)

  • Builds the current query.
  • Returns the Search chainable.

  Gmail.labels.exists(label)

  • Return True or False if the label exists.

  Gmail.labels.switch(label)

  • Change the current label.
  • This clears the current search.

  Gmail.labels.create(label)

  • Create a label.

  Gmail.labels.delete(label)

  • Delete a label.

  Gmail.labels.rename(old, new)

  • Rename a label.

  Gmail.labels.all()

  • Return a list of current labels.

  Gmail.labels.current

  • The current label.

  Gmail.labels.count

  • The number of messages in the current label.

  Message.init(options)

  • Options are used internally.
  • If you are creating a message to send, don't fill in any options.
  • Instead, do '> msg = Message().fill(your content)'.

  Message.fill(to_addresses='', from_address='', subject='', body='')

  • Create a message to send.
  • Returns itself.

  Message.fetch()

  • Downloads the content of a message from the server.
  • Returns itself.

  Message.from_address(address)

  • If 'address' is omitted, returns the current from address.
  • Otherwise sets the from address.

  Message.to_address(address)

  • If 'address' is omitted, returns the current list of to addresses.
  • Otherwise sets the to addresses.
  • 'address' can be a string or list.

  Message.subject(subject)

  • If 'subject' is omitted, returns the current subject.
  • Otherwise sets the subject.

  Message.body(body)

  • If 'body' is omitted, returns the current message body.
  • Otherwise sets the message body.

  Message.read() Message.unread()

  • Mark a message as read/unread.

  Message.delete()

  • Delete a message from the current label.

  Message.archive()

  • Archive a message.

  Message.star() Message.unstar()

  • Star/Unstar a message.

  Message.spam()

  • Mark a message as spam.

  Message.flag(flag) Message.unflag(flag)

  • Typically internal commands, add/remove a flag for a message.

  Message.add_label(label)

  • Add a label to the message.

  Message.move_to(label)

  • Move a message to a new label.