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

disable logging.

enable_logging()

re-enable logging.

get_info()

return dictionary of built config parameters.

set_stock_translation(id, string)

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

update_config(kwargs)

update config values.

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.

set_avatar(img_path)

Set self avatar.

Raises

ValueError – if profile image could not be set

Returns

None

check_is_configured()

Raise ValueError if this account is not configured.

get_latest_backupfile(backupdir)

return the latest backup file in a given directory.

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

Returns

deltachat.contact.Contact

create_contact(obj, name=None)

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)

delete a Contact.

Parameters

contact – contact object obtained

Returns

True if deletion succeeded (contact was deleted)

get_contact_by_addr(email)

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

get_contact_by_id(contact_id)

return Contact instance or None. :param contact_id: integer id of this contact. :returns: None or deltachat.contact.Contact instance.

get_blocked_contacts()

return a list of all blocked contacts.

Returns

list of deltachat.contact.Contact objects.

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

get_fresh_messages()

yield all fresh messages from all chats.

create_chat(obj)

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

create_group_chat(name, contacts=None, verified=False)

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

return list of chats.

Returns

a list of deltachat.chat.Chat objects.

get_message_by_id(msg_id)

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

get_chat_by_id(chat_id)

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)

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

Returns

None

delete_messages(messages)

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 does not have to be started.

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

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

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=0.0, longitude=0.0, accuracy=0.0)

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

configure()

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

wait until shutdown of this account has completed.

stop_io()

stop core IO scheduler if it is running.

shutdown()

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

normalized e-mail address for this account.

property name

display name for this contact.

property display_name

display name for this contact.

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

Get contact profile image.

Returns

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

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

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

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

return true if this chat is a deaddrop chat.

Returns

True if chat is the deaddrop chat, False otherwise.

is_muted()

return true if this chat is muted.

Returns

True if chat is muted, 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()

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

Returns

True if the chat is writable, False otherwise

is_protected()

return True if this chat is a protected chat.

Returns

True if chat is protected, False otherwise.

get_name()

return name of this chat.

Returns

unicode name

set_name(name)

set name of this chat.

Parameters

name – as a unicode string.

Returns

None

mute(duration=None)

mutes the chat

Parameters

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

Returns

None

unmute()

unmutes the chat

Returns

None

get_mute_duration()

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

get ephemeral timer.

Returns

ephemeral timer value in seconds

set_ephemeral_timer(timer)

set ephemeral timer.

Param

timer value in seconds

Returns

None

get_type()

(deprecated) return type of this chat.

Returns

one of const.DC_CHAT_TYPE_*

get_join_qr()

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)

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)

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.

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 “text”, “audio”, “video”, “file”

create_chat()

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

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

Returns

a deltachat.chat.Chat object.

property text

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

set_text(text)

set text of this message.

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

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

property filemime

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

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

is_encrypted()

return True if this message was encrypted.

is_forwarded()

return True if this message was forwarded.

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.

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

Text inside the quote

Returns

Quoted text

property quote

Quote getter

Returns

Quoted message, if found in the database

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 chat

chat this message was posted in.

Returns

deltachat.chat.Chat object

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