high level API reference

Note

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

Account

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

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()[source]

return dictionary of built config parameters.

set_config(name, value)[source]

set configuration values.

Parameters:
  • name – config key name (unicode)
  • value – value to set (unicode)
Returns:

None

get_config(name)[source]

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)[source]

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()[source]

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()[source]

Raise ValueError if this account is not configured.

get_infostring()[source]

return info of the configured account.

get_blobdir()[source]

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()[source]

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

Returns:deltachat.chatting.Contact
create_message(view_type)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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()[source]

return list of chats.

Returns:a list of deltachat.chatting.Chat objects.
get_message_by_id(msg_id)[source]

return Message instance.

mark_seen_messages(messages)[source]

mark the given set of messages as seen.

Parameters:messages – a list of message ids or Message instances.
forward_messages(messages, chat)[source]

Forward list of messages to a chat.

Parameters:
Returns:

None

delete_messages(messages)[source]

delete messages (local and remote).

Parameters:messages – list of deltachat.chatting.Message object.
Returns:None
start_threads()[source]

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()[source]

stop IMAP/SMTP threads.

Contact

class deltachat.chatting.Contact(dc_context, id)[source]

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()[source]

Return True if the contact is blocked.

is_verified()[source]

Return True if the contact is verified.

Chat

class deltachat.chatting.Chat(dc_context, id)[source]

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

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

delete()[source]

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()[source]

return true if this chat is a deaddrop chat.

Returns:True if chat is the deaddrop chat, False otherwise.
is_promoted()[source]

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()[source]

return name of this chat.

Returns:unicode name
set_name(name)[source]

set name of this chat.

Param:name as a unicode string.
Returns:None
send_text(text)[source]

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')[source]

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)[source]

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')[source]

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)[source]

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()[source]

return list of messages in this chat.

Returns:list of deltachat.chatting.Message objects for this chat.
count_fresh_messages()[source]

return number of fresh messages in this chat.

Returns:number of fresh messages
mark_noticed()[source]

mark all messages in this chat as noticed.

Noticed messages are no longer fresh.

add_contact(contact)[source]

add a contact to this chat.

Params:contact object.
Exception:ValueError if contact could not be added
Returns:None
get_contacts()[source]

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)[source]

Message object.

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

classmethod new(dc_context, view_type)[source]

create a non-persistent method.

get_state()[source]

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)[source]

set text of this message.

filename

filename if there was an attachment, otherwise empty string.

set_file(path, mime_type=None)[source]

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()[source]

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()[source]

return the contact of who wrote the message.

Returns:deltachat.chatting.Contact instance

MessageType

MessageState