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.message.Message

Account

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

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_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.

delete_contact(contact)

delete a Contact.

Parameters

contact – contact object obtained

Returns

True if deletion succeeded (contact was deleted)

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.Contact objects.

create_chat_by_contact(contact)

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

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.message.Message object.

• chat – deltachat.chatting.Chat object.

Returns

None

delete_messages(messages)

delete messages (local and remote).

Parameters

messages – list of deltachat.message.Message object.

Returns

None

export_to_dir(backupdir)

return after all delta chat state is exported to a new file in the specified directory.

import_from_file(path)

import delta chat state from the specified backup file.

The account must be in unconfigured state for import to attempted.

initiate_key_transfer()

return setup code after a Autocrypt setup message has been successfully sent to our own e-mail address (“self-sent message”). If sending out was unsuccessful, a RuntimeError is raised.

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(wait=True)

stop IMAP/SMTP threads.

shutdown(wait=True)

stop threads and close and remove underlying dc_context and callbacks.

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(account, 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

get_type()

return type of this chat.

Returns

one of const.DC_CHAT_TYPE_*

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.message.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.message.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.message.Message instance

prepare_message(msg)

create a new prepared message.

Parameters

msg – the message to be prepared.

Returns

deltachat.message.Message instance.

prepare_message_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 – “text”, “image”, “gif”, “audio”, “video”, “file”

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.message.Message instance as sent out.

set_draft(message)

set message as draft.

Parameters

message – a Message instance

Returns

None

get_draft()

get draft message for this chat.

Parameters

message – a Message instance

Returns

Message object or None (if no draft available)

get_messages()

return list of messages in this chat.

Returns

list of deltachat.message.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.

Raises

ValueError – if contact could not be added

Returns

None

remove_contact(contact)

remove a contact from this chat.

Params

contact object.

Raises

ValueError – if contact could not be removed

Returns

None

get_contacts()

get all contacts for this chat. :params: contact object. :raises ValueError: if contact could not be added :returns: list of deltachat.chatting.Contact objects for this chat

Message

class deltachat.message.Message(account, dc_msg)

Message object.

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

classmethod new_empty(account, view_type)

create a non-persistent message.

Param

view_type is “text”, “audio”, “video”, “file”

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 from path and mime_type.

basename

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

filemime

mime type of the file (if it exists)

is_setup_message()

return True if this message is a setup message.

get_message_info()

Return informational text for a single message.

The text is multiline and may contain eg. the raw text of the message.

continue_key_transfer(setup_code)

extract key and use it as primary key for this account.

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

is_in_fresh()

return True if Message is incoming fresh message (un-noticed).

Fresh messages are not noticed nor seen and are typically shown in notifications.

is_in_noticed()

Return True if Message is incoming and noticed.

Eg. chat opened but message not yet read - noticed messages are not counted as unread but were not marked as read nor resulted in MDNs.

is_in_seen()

Return True if Message is incoming, noticed and has been seen.

Eg. chat opened but message not yet read - noticed messages are not counted as unread but were not marked as read nor resulted in MDNs.

is_out_preparing()

Return True if Message is outgoing, but its file is being prepared.

is_out_pending()

Return True if Message is outgoing, but is pending (no single checkmark).

is_out_failed()

Return True if Message is unrecoverably failed.

is_out_delivered()

Return True if Message was successfully delivered to the server (one checkmark).

Note, that already delivered messages may get into the state is_out_failed().

is_out_mdn_received()

Return True if message was marked as read by the recipient(s) (two checkmarks; this requires goodwill on the receiver’s side). If a sent message changes to this state, you’ll receive the event DC_EVENT_MSG_READ.

is_text()

return True if it’s a text message.

is_image()

return True if it’s an image message.

is_gif()

return True if it’s a gif message.

is_audio()

return True if it’s an audio message.

is_video()

return True if it’s a video message.

is_file()

return True if it’s a file message.