high level API reference

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

• deltachat.Contact

• deltachat.Chat

• deltachat.Message

Account

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

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.

open(passphrase: str | None = None) → bool

Open the account’s database with the given passphrase. This can only be used on a closed account. If the account is new, this operation sets the database passphrase. For existing databases the passphrase should be the one used to encrypt the database the first time.

Returns:

True if the database is opened with this passphrase, False if the passphrase is incorrect or an error occurred.

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 translation

Returns:

None

set_config(name: str, value: str | None) → 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: str | None) → 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) → str | None

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

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

Returns:

deltachat.contact.Contact

create_contact(obj, name: str | None = None) → 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: Contact) → bool

delete a Contact.

Parameters:

contact – contact object obtained

Returns:

True if deletion succeeded (contact was deleted)

get_contact_by_addr(email: str) → Contact | None

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

get_contact_by_id(contact_id: int) → 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[Contact]

return a list of all blocked contacts.

Returns:

list of deltachat.contact.Contact objects.

get_contacts(query: str | None = None, with_self: bool = False, only_verified: bool = False) → List[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[Message, None, None]

yield all fresh messages from all chats.

wait_next_incoming_message() → Message

Waits until the next incoming message with ID higher than given is received and returns it.

create_chat(obj) → Chat

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

create_group_chat(name: str, contacts: List[Contact] | None = None, verified: bool = False) → 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[Chat]

return list of chats.

Returns:

a list of deltachat.chat.Chat objects.

get_message_by_id(msg_id: int) → Message | None

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

get_chat_by_id(chat_id: int) → 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[int | Message]) → None

mark the given set of messages as seen.

Parameters:

messages – a list of message ids or Message instances.

forward_messages(messages: List[Message], 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[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: str, passphrase: str | None = None) → str

Export a backup of all database state (chats, contacts, keys, media, …).

Parameters:

• path – the directory where the backup will be stored.

• passphrase – the backup will be encrypted with the passphrase, if it is None or empty string, the backup is not encrypted.

Returns:

path to the created backup.

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: str, passphrase: str | None = None) → None

Import Delta Chat state from the specified backup file. The account must be in unconfigured state for import to attempted.

Parameters:

• path – path to the backup file.

• passphrase – if not None or empty, the backup will be opened with the passphrase.

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() → 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(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: 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() → bool

Return True if the contact is verified.

get_verifier(contact)

Return the address of the contact that verified the contact.

get_profile_image() → str | None

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(account, id: int)

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 otherwise

is_single() → bool

Return True if this chat is a single/direct chat, False otherwise.

is_mailinglist() → bool

Return True if this chat is a mailing list, False otherwise.

is_broadcast() → bool

Return True if this chat is a broadcast list, False otherwise.

is_multiuser() → bool

Return True if this chat is a multi-user chat (group, mailing list or broadcast), False otherwise.

is_self_talk() → bool

Return True if this chat is the self-chat (a.k.a. “Saved Messages”), False otherwise.

is_device_talk() → bool

Returns True if this chat is the “Device Messages” chat, False otherwise.

is_muted() → bool

return true if this chat is muted.

Returns:

True if chat is muted, False otherwise.

is_pinned() → bool

Return True if this chat is pinned, False otherwise.

is_archived() → bool

Return True if this chat is archived, False otherwise. :returns: True if archived, False otherwise.

is_contact_request() → bool

return True if this chat is a contact request chat.

Returns:

True if chat is a contact request chat, False otherwise.

is_promoted() → bool

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() → str | None

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

get_color()

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

get_summary()

return dictionary with summary information.

mute(duration: int | None = 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

pin() → None

Pin the chat.

unpin() → None

Unpin the chat.

archive() → None

Archive the chat.

unarchive() → None

Unarchive the chat.

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() → str | None

Return encryption info for this chat.

Returns:

a string with encryption preferences of all chat members

get_join_qr() → str | None

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

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.

is_sending_locations() → bool

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

enable_sending_locations(seconds) → None

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

Message object.

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

classmethod from_db(account, id) → Message | None

Attempt to load the message from the database given its ID.

None is returned if the message does not exist, i.e. deleted.

classmethod new_empty(account, view_type)

create a non-persistent message.

Parameters:

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

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

get_status_updates(serial: int = 0) → list

Get the status updates of this webxdc message.

The status updates may be sent by yourself or by other members. If this message doesn’t have a webxdc instance, an empty list is returned.

Parameters:

serial – The last known serial. Pass 0 if there are no known serials to receive all updates.

send_status_update(json_data: str | dict, description: str) → bool

Send an status update for the webxdc instance of this message.

If the webxdc instance is a draft, the update is not sent immediately. Instead, the updates are collected and sent out in a batch when the instance is actually sent.

Parameters:

• json_data – program-readable data, the actual payload.

• description – The user-visible description of JSON data

Returns:

True on success, False otherwise

send_reaction(reaction: str)

Send a reaction to message and return the resulting Message instance.

get_reactions() → Reactions

Get deltachat.reactions.Reactions to the message.

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.

get_summarytext(width: int) → str

Get a message summary as a single line of text. Typically used for notifications.

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: str | None

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: str | None

Error message.

property chat

chat this message was posted in.

Returns:

deltachat.chat.Chat object

property override_sender_name: str | None

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

Return true if the message is sent by self.

is_from_device()

Return true if the message is sent by the device.

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

return True if it’s a videochat invitation message.

is_webxdc()

return True if it’s a Webxdc message.

is_file()

return True if it’s a file message.

mark_seen()

mark this message as seen.