high level API reference

• deltachat.account.Account (your main entry point, creates the other classes)

• deltachat.contact.Contact

• deltachat.chat.Chat

• deltachat.message.Message

Account

class deltachat.account.Account(db_path, os_name=None, logging=True)

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

exception MissingCredentials

Account is missing addr and mail_pw config values.

disable_logging() → None

disable logging.

enable_logging() → None

re-enable logging.

get_info() → Dict[str, str]

return dictionary of built config parameters.

set_stock_translation(id: int, string: str) → None

set stock translation string.

Parameters

• id – id of stock string (const.DC_STR_*)

• value – string to set as new transalation

Returns

None

set_config(name: str, value: Optional[str]) → None

set configuration values.

Parameters

• name – config key name (unicode)

• value – value to set (unicode)

Returns

None

get_config(name: str) → str

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.

update_config(kwargs: Dict[str, Any]) → None

update config values.

Parameters

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

Returns

None

is_configured() → bool

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

Returns

True if account is configured.

is_open() → bool

Determine if account is open

:returns True if account is open.

set_avatar(img_path: Optional[str]) → None

Set self avatar.

Raises

ValueError – if profile image could not be set

Returns

None

check_is_configured() → None

Raise ValueError if this account is not configured.

get_latest_backupfile(backupdir) → Optional[str]

return the latest backup file in a given directory.

get_blobdir() → str

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() → deltachat.contact.Contact

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

Returns

deltachat.contact.Contact

create_contact(obj, name: Optional[str] = None) → deltachat.contact.Contact

create a (new) Contact or return an existing one.

Calling this method will always result in the same underlying contact id. If there already is a Contact with that e-mail address, it is unblocked and its display name is updated if specified.

Parameters

• obj – email-address, Account or Contact instance.

• name – (optional) display name for this contact

Returns

deltachat.contact.Contact instance.

delete_contact(contact: deltachat.contact.Contact) → bool

delete a Contact.

Parameters

contact – contact object obtained

Returns

True if deletion succeeded (contact was deleted)

get_contact_by_addr(email: str) → Optional[deltachat.contact.Contact]

get a contact for the email address or None if it’s blocked or doesn’t exist.

get_contact_by_id(contact_id: int) → deltachat.contact.Contact

return Contact instance or raise an exception. :param contact_id: integer id of this contact. :returns: deltachat.contact.Contact instance.

get_blocked_contacts() → List[deltachat.contact.Contact]

return a list of all blocked contacts.

Returns

list of deltachat.contact.Contact objects.

get_contacts(query: Optional[str] = None, with_self: bool = False, only_verified: bool = False) → List[deltachat.contact.Contact]

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

get_fresh_messages() → Generator[deltachat.message.Message, None, None]

yield all fresh messages from all chats.

create_chat(obj) → deltachat.chat.Chat

Create a 1:1 chat with Account, Contact or e-mail address.

create_group_chat(name: str, contacts: Optional[List[deltachat.contact.Contact]] = None, verified: bool = False) → deltachat.chat.Chat

create a new group chat object.

Chats are unpromoted until the first message is sent.

Parameters

• contacts – list of contacts to add

• verified – if true only verified contacts can be added.

Returns

a deltachat.chat.Chat object.

get_chats() → List[deltachat.chat.Chat]

return list of chats.

Returns

a list of deltachat.chat.Chat objects.

get_message_by_id(msg_id: int) → deltachat.message.Message

return Message instance. :param msg_id: integer id of this message. :returns: deltachat.message.Message instance.

get_chat_by_id(chat_id: int) → deltachat.chat.Chat

return Chat instance. :param chat_id: integer id of this chat. :returns: deltachat.chat.Chat instance. :raises: ValueError if chat does not exist.

mark_seen_messages(messages: List[Union[int, deltachat.message.Message]]) → None

mark the given set of messages as seen.

Parameters

messages – a list of message ids or Message instances.

forward_messages(messages: List[deltachat.message.Message], chat: deltachat.chat.Chat) → None

Forward list of messages to a chat.

Parameters

• messages – list of deltachat.message.Message object.

• chat – deltachat.chat.Chat object.

Returns

None

delete_messages(messages: List[deltachat.message.Message]) → None

delete messages (local and remote).

Parameters

messages – list of deltachat.message.Message object.

Returns

None

export_self_keys(path)

export public and private keys to the specified directory.

Note that the account does not have to be started.

export_all(path)

return new file containing a backup of all database state (chats, contacts, keys, media, …). The file is created in the the path directory.

Note that the account has to be stopped; call stop_io() if necessary.

import_self_keys(path)

Import private keys found in the path directory. The last imported key is made the default keys unless its name contains the string legacy. Public keys are not imported.

Note that the account does not have to be started.

import_all(path)

import delta chat state from the specified backup path (a file).

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

initiate_key_transfer() → str

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.

get_setup_contact_qr() → str

get/create Setup-Contact QR Code as ascii-string.

this string needs to be transferred to another DC account in a second channel (typically used by mobiles with QRcode-show + scan UX) where qr_setup_contact(qr) is called.

check_qr(qr)

check qr code and return ScannedQRCode instance representing the result

qr_setup_contact(qr)

setup contact and return a Chat after contact is established.

Note that this function may block for a long time as messages are exchanged with the emitter of the QR code. On success a deltachat.chat.Chat instance is returned. :param qr: valid “setup contact” QR code (all other QR codes will result in an exception)

qr_join_chat(qr)

join a chat group through a QR code.

Note that this function may block for a long time as messages are exchanged with the emitter of the QR code. On success a deltachat.chat.Chat instance is returned which is the chat that we just joined.

Parameters

qr – valid “join-group” QR code (all other QR codes will result in an exception)

set_location(latitude: float = 0.0, longitude: float = 0.0, accuracy: float = 0.0) → None

set a new location. It effects all chats where we currently have enabled location streaming.

Parameters

• latitude – float (use 0.0 if not known)

• longitude – float (use 0.0 if not known)

• accuracy – float (use 0.0 if not known)

Raises

ValueError if no chat is currently streaming locations

Returns

None

add_account_plugin(plugin, name=None)

add an account plugin which implements one or more of the deltachat.hookspec.PerAccount hooks.

remove_account_plugin(plugin, name=None)

remove an account plugin.

temp_plugin(plugin)

run a with-block with the given plugin temporarily registered.

stop_ongoing()

Stop ongoing securejoin, configuration or other core jobs.

start_io()

start this account’s IO scheduling (Rust-core async scheduler)

If this account is not configured an Exception is raised. You need to call account.configure() and account.wait_configure_finish() before.

You may call stop_scheduler, wait_shutdown or shutdown after the account is started.

If you are using this from a test, you may want to call wait_all_initial_fetches() afterwards.

Raises

• MissingCredentials – if addr and mail_pw values are not set.

• ConfigureFailed – if the account could not be configured.

Returns

None

maybe_network()

This function should be called when there is a hint that the network is available again, e.g. as a response to system event reporting network availability. The library will try to send pending messages out immediately.

Moreover, to have a reliable state when the app comes to foreground with network available, it may be reasonable to call the function also at that moment.

It is okay to call the function unconditionally when there is network available, however, calling the function _without_ having network may interfere with the backoff algorithm and will led to let the jobs fail faster, with fewer retries and may avoid messages being sent out.

Finally, if the context was created by the dc_accounts_t account manager (currently not implemented in the Python bindings), use dc_accounts_maybe_network() instead of this function

configure(reconfigure: bool = False) → deltachat.tracker.ConfigureTracker

Start configuration process and return a Configtracker instance on which you can block with wait_finish() to get a True/False success value for the configuration process.

wait_shutdown() → None

wait until shutdown of this account has completed.

stop_io() → None

stop core IO scheduler if it is running.

shutdown() → None

shutdown and destroy account (stop callback thread, close and remove underlying dc_context).

Contact

class deltachat.contact.Contact(account, id)

Delta-Chat Contact.

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

property addr: str

normalized e-mail address for this account.

property name: str

display name for this contact.

property display_name: str

display name for this contact.

property last_seen: datetime.date

Last seen timestamp.

is_blocked()

Return True if the contact is blocked.

set_blocked(block=True)

[Deprecated, use block/unblock methods] Block or unblock a contact.

block()

Block this contact. Message will not be seen/retrieved from this contact.

unblock()

Unblock this contact. Messages from this contact will be retrieved (again).

is_verified()

Return True if the contact is verified.

get_profile_image() → Optional[str]

Get contact profile image.

Returns

path to profile image, None if no profile image exists.

property status

Get contact status.

Returns

contact status, empty string if it doesn’t exist.

create_chat()

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.chat.Chat object.

get_chat()

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.chat.Chat object.

Chat

class deltachat.chat.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() → None

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

block() → None

Block this chat.

accept() → None

Accept this contact request chat.

is_group() → bool

return true if this chat is a group chat.

Returns

True if chat is a group-chat, false if it’s a contact 1:1 chat.

is_muted() → bool

return true if this chat is muted.

Returns

True if chat is muted, False otherwise.

is_contact_request()

return True if this chat is a contact request chat.

Returns

True if chat is a contact request 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.

can_send() → bool

Check if messages can be sent to a give chat. This is not true eg. for the contact requests or for the device-talk

Returns

True if the chat is writable, False otherwise

is_protected() → bool

return True if this chat is a protected chat.

Returns

True if chat is protected, False otherwise.

get_name() → Optional[str]

return name of this chat.

Returns

unicode name

set_name(name: str) → bool

set name of this chat.

Parameters

name – as a unicode string.

Returns

True on success, False otherwise

mute(duration: Optional[int] = None) → None

mutes the chat

Parameters

duration – Number of seconds to mute the chat for. None to mute until unmuted again.

Returns

None

unmute() → None

unmutes the chat

Returns

None

get_mute_duration() → int

Returns the number of seconds until the mute of this chat is lifted.

Parameters

duration –

Returns

Returns the number of seconds the chat is still muted for. (0 for not muted, -1 forever muted)

get_ephemeral_timer() → int

get ephemeral timer.

Returns

ephemeral timer value in seconds

set_ephemeral_timer(timer: int) → bool

set ephemeral timer.

Param

timer value in seconds

Returns

True on success, False otherwise

get_type() → int

(deprecated) return type of this chat.

Returns

one of const.DC_CHAT_TYPE_*

get_encryption_info() → Optional[str]

Return encryption info for this chat.

Returns

a string with encryption preferences of all chat members

get_join_qr() → Optional[str]

get/create Join-Group QR Code as ascii-string.

this string needs to be transferred to another DC account in a second channel (typically used by mobiles with QRcode-show + scan UX) where account.join_with_qrcode(qr) needs to be called.

send_msg(msg: deltachat.message.Message) → deltachat.message.Message

send a message by using a ready Message object.

Parameters

msg – a deltachat.message.Message instance previously returned by e.g. deltachat.message.Message.new_empty() or prepare_file().

Raises

ValueError – if message can not be sent.

Returns

a deltachat.message.Message instance as sent out. This is the same object as was passed in, which has been modified with the new state of the core.

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)

prepare a message for sending.

Parameters

msg – the message to be prepared.

Returns

a deltachat.message.Message instance. This is the same object that was passed in, which has been modified with the new state of the core.

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.

get_summary()

return dictionary with summary information.

add_contact(obj)

add a contact to this chat.

Params obj

Contact, Account or e-mail address.

Raises

ValueError – if contact could not be added

Returns

None

remove_contact(obj)

remove a contact from this chat.

Params obj

Contact, Account or e-mail address.

Raises

ValueError – if contact could not be removed

Returns

None

get_contacts()

get all contacts for this chat. :returns: list of deltachat.contact.Contact objects for this chat

num_contacts()

return number of contacts in this chat.

set_profile_image(img_path)

Set group profile image.

If the group is already promoted (any message was sent to the group), all group members are informed by a special status message that is sent automatically by this function. :params img_path: path to image object :raises ValueError: if profile image could not be set :returns: None

remove_profile_image()

remove group profile image.

If the group is already promoted (any message was sent to the group), all group members are informed by a special status message that is sent automatically by this function. :raises ValueError: if profile image could not be reset :returns: None

get_profile_image()

Get group profile image.

For groups, this is the image set by any group member using set_chat_profile_image(). For normal chats, this is the image set by each remote user on their own using dc_set_config(context, “selfavatar”, image). :returns: path to profile image, None if no profile image exists.

get_color()

return the color of the chat. :returns: color as 0x00rrggbb

is_sending_locations()

return True if this chat has location-sending enabled currently. :returns: True if location sending is enabled.

is_archived()

return True if this chat is archived. :returns: True if archived.

enable_sending_locations(seconds)

enable sending locations for this chat.

all subsequent messages will carry a location with them.

get_locations(contact=None, timestamp_from=None, timestamp_to=None)

return list of locations for the given contact in the given timespan.

Parameters

• contact – the contact for which locations shall be returned.

• timespan_from – a datetime object or None (indicating “since beginning”)

• timespan_to – a datetime object or None (indicating up till now)

Returns

list of deltachat.chat.Location objects.

Message

class deltachat.message.Message(account, dc_msg)

Message object.

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

classmethod new_empty(account, view_type)

create a non-persistent message.

Param

view_type is the message type code or one of the strings: “text”, “audio”, “video”, “file”, “sticker”

create_chat()

create or get an existing chat (group) object for this message.

If the message is a contact request the sender will become an accepted contact.

Returns

a deltachat.chat.Chat object.

property id

id of this message.

property text: str

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

set_text(text)

set text of this message.

property html: str

html text of this messages (might be empty if not an html message).

has_html()

return True if this message has an html part, False otherwise.

set_html(html_text)

set the html part of this message.

It is possible to have text and html part at the same time.

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

property basename: str

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

property filemime: str

mime type of the file (if it exists)

is_system_message()

return True if this message is a system/info message.

is_setup_message()

return True if this message is a setup message.

get_setupcodebegin() → str

return the first characters of a setup code in a setup message.

is_encrypted()

return True if this message was encrypted.

is_bot()

return True if this message is submitted automatically.

is_forwarded()

return True if this message was forwarded.

get_message_info() → str

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.

property time_sent

UTC time when the message was sent.

Returns

naive datetime.datetime() object.

property time_received

UTC time when the message was received.

Returns

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

property ephemeral_timer

Ephemeral timer in seconds

Returns

timer in seconds or None if there is no timer

property ephemeral_timestamp

UTC time when the message will be deleted.

Returns

naive datetime.datetime() object or None if the timer is not started.

property quoted_text: Optional[str]

Text inside the quote

Returns

Quoted text

property quote

Quote getter

Returns

Quoted message, if found in the database

force_plaintext() → None

Force the message to be sent in plain text.

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

property error: Optional[str]

Error message

property chat

chat this message was posted in.

Returns

deltachat.chat.Chat object

property override_sender_name: Optional[str]

the name that should be shown over the message instead of the contact display name.

Usually used to impersonate someone else.

set_override_sender_name(name)

set different sender name for a message.

get_sender_chat()

return the 1:1 chat with the sender of this message.

Returns

deltachat.chat.Chat instance

get_sender_contact()

return the contact of who wrote the message.

Returns

deltachat.chat.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_outgoing()

Return True if Message is outgoing.

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_sticker()

return True if it’s a sticker 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.

mark_seen()

mark this message as seen.