high level API reference

Note

This API is work in progress and may change in versions prior to 1.0.

• deltachat.account.Account (your main entry point, creates the other classes)
• deltachat.chatting.Contact
• deltachat.chatting.Chat
• deltachat.chatting.Message
• deltachat.chatting.MessageType
• deltachat.chatting.MessageState

Account

class deltachat.account.Account(db_path, logid=None)

Each account is tied to a sqlite database file which is fully managed by the underlying deltachat c-library. All public Account methods are meant to be memory-safe and return memory-safe objects.

get_info()

return dictionary of built config parameters.

set_config(name, value)

set configuration values.

Parameters:

• name – config key name (unicode)
• value – value to set (unicode)

Returns:

None

get_config(name)

return unicode string value.

Parameters:name – configuration key to lookup (eg “addr” or “mail_pw”) Returns:unicode value Raises:KeyError if no config value was found.

configure(**kwargs)

set config values and configure this account.

Parameters:kwargs – name=value config settings for this account. values need to be unicode. Returns:None

is_configured()

determine if the account is configured already; an initial connection to SMTP/IMAP has been verified.

Returns:True if account is configured.

check_is_configured()

Raise ValueError if this account is not configured.

get_infostring()

return info of the configured account.

get_blobdir()

return the directory for files.

All sent files are copied to this directory if necessary. Place files there directly to avoid copying.

get_self_contact()

return this account’s identity as a deltachat.chatting.Contact.

Returns:deltachat.chatting.Contact

create_message(view_type)

create a new non persistent message.

Parameters:view_type – a string specifying “text”, “video”, “image”, “audio” or “file”. Returns:deltachat.chatting.Message instance.

create_contact(email, name=None)

create a (new) Contact. If there already is a Contact with that e-mail address, it is unblocked and its name is updated.

Parameters:

• email – email-address (text type)
• name – display name for this contact (optional)

Returns:

deltachat.chatting.Contact instance.

get_contacts(query=None, with_self=False, only_verified=False)

get a (filtered) list of contacts.

Parameters:

• query – if a string is specified, only return contacts whose name or e-mail matches query.
• only_verified – if true only return verified contacts.
• with_self – if true the self-contact is also returned.

Returns:

list of deltachat.chatting.Message objects.

create_chat_by_contact(contact)

create or get an existing 1:1 chat object for the specified contact.

Parameters:contact – chat_id (int) or contact object. Returns:a deltachat.chatting.Chat object.

create_chat_by_message(message)

create or get an existing chat object for the the specified message.

Parameters:message – messsage id or message instance. Returns:a deltachat.chatting.Chat object.

create_group_chat(name, verified=False)

create a new group chat object.

Chats are unpromoted until the first message is sent.

Parameters:verified – if true only verified contacts can be added. Returns:a deltachat.chatting.Chat object.

get_chats()

return list of chats.

Returns:a list of deltachat.chatting.Chat objects.

get_message_by_id(msg_id)

return Message instance.

mark_seen_messages(messages)

mark the given set of messages as seen.

Parameters:messages – a list of message ids or Message instances.

forward_messages(messages, chat)

Forward list of messages to a chat.

Parameters:

• messages – list of deltachat.chatting.Message object.
• chat – deltachat.chatting.Chat object.

Returns:

None

delete_messages(messages)

delete messages (local and remote).

Parameters:messages – list of deltachat.chatting.Message object. Returns:None

start_threads()

start IMAP/SMTP threads (and configure account if it hasn’t happened).

Raises:ValueError if ‘addr’ or ‘mail_pw’ are not configured. Returns:None

stop_threads()

stop IMAP/SMTP threads.

Contact

class deltachat.chatting.Contact(dc_context, id)

Delta-Chat Contact.

You obtain instances of it through deltachat.account.Account.

addr

normalized e-mail address for this account.

display_name

display name for this contact.

is_blocked()

Return True if the contact is blocked.

is_verified()

Return True if the contact is verified.

Chat

class deltachat.chatting.Chat(dc_context, id)

Chat object which manages members and through which you can send and retrieve messages.

You obtain instances of it through deltachat.account.Account.

delete()

Delete this chat and all its messages.

Note:

• does not delete messages on server
• the chat or contact is not blocked, new message will arrive

is_deaddrop()

return true if this chat is a deaddrop chat.

Returns:True if chat is the deaddrop chat, False otherwise.

is_promoted()

return True if this chat is promoted, i.e. the member contacts are aware of their membership, have been sent messages.

Returns:True if chat is promoted, False otherwise.

get_name()

return name of this chat.

Returns:unicode name

set_name(name)

set name of this chat.

Param:name as a unicode string. Returns:None

send_text(text)

send a text message and return the resulting Message instance.

Parameters:msg – unicode text Raises:ValueError if message can not be send/chat does not exist. Returns:the resulting deltachat.chatting.Message instance

send_file(path, mime_type='application/octet-stream')

send a file and return the resulting Message instance.

Parameters:

• path – path to the file.
• mime_type – the mime-type of this file, defaults to application/octet-stream.

Raises:

ValueError if message can not be send/chat does not exist.

Returns:

the resulting deltachat.chatting.Message instance

send_image(path)

send an image message and return the resulting Message instance.

Parameters:path – path to an image file. Raises:ValueError if message can not be send/chat does not exist. Returns:the resulting deltachat.chatting.Message instance

prepare_file(path, mime_type=None, view_type='file')

prepare a message for sending and return the resulting Message instance.

To actually send the message, call send_prepared(). The file must be inside the blob directory.

Parameters:

• path – path to the file.
• mime_type – the mime-type of this file, defaults to auto-detection.
• view_type – passed to MessageType.new().

Raises:

ValueError if message can not be prepared/chat does not exist.

Returns:

the resulting Message instance

send_prepared(message)

send a previously prepared message.

Parameters:message – a Message instance previously returned by prepare_file(). Raises:ValueError if message can not be sent. Returns:a deltachat.chatting.Message instance with updated state

get_messages()

return list of messages in this chat.

Returns:list of deltachat.chatting.Message objects for this chat.

count_fresh_messages()

return number of fresh messages in this chat.

Returns:number of fresh messages

mark_noticed()

mark all messages in this chat as noticed.

Noticed messages are no longer fresh.

add_contact(contact)

add a contact to this chat.

Params:contact object. Exception:ValueError if contact could not be added Returns:None

get_contacts()

get all contacts for this chat.

Params:contact object. Exception:ValueError if contact could not be added Returns:None

Message

class deltachat.chatting.Message(dc_context, id)

Message object.

You obtain instances of it through deltachat.account.Account or deltachat.chatting.Chat.

classmethod new(dc_context, view_type)

create a non-persistent method.

get_state()

get the message in/out state.

Returns:deltachat.chatting.MessageState

text

unicode text of this messages (might be empty if not a text message).

set_text(text)

set text of this message.

filename

filename if there was an attachment, otherwise empty string.

set_file(path, mime_type=None)

set file for this message.

basename

basename of the attachment if it exists, otherwise empty string.

filemime

mime type of the file (if it exists)

view_type

the view type of this message.

Returns:a deltachat.chatting.MessageType instance.

time_sent

UTC time when the message was sent.

Returns:naive datetime.datetime() object.

time_received

UTC time when the message was received.

Returns:naive datetime.datetime() object or None if message is an outgoing one.

get_mime_headers()

return mime-header object for an incoming message.

This only returns a non-None object if save_mime_headers config option was set and the message is incoming.

Returns:email-mime message object (with headers only, no body).

chat

chat this message was posted in.

Returns:deltachat.chatting.Chat object

get_sender_contact()

return the contact of who wrote the message.

Returns:deltachat.chatting.Contact instance

MessageType

MessageState