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

• deltachat.chat.Chat

• deltachat.message.Message

Account

class deltachat.account.Account(db_path, logid=None, eventlogging=True, os_name=None, debug=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.

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.

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.

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.

empty_server_folders(inbox=False, mvbox=False)

empty server folders.

get_infostring()

return info of the configured account.

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(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.contact.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.contact.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.chat.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.chat.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.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.

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.

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.

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)

wait_next_incoming_message()

wait for and return next incoming message.

start_threads(mvbox=False, sentbox=False)

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.

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

Contact

class deltachat.contact.Contact(dc_context, id)

Delta-Chat Contact.

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

property addr

normalized e-mail address for this account.

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

get_profile_image()

Get contact profile image.

Returns

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

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

is_verified()

return True if this chat is a verified group.

Returns

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

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(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. :returns: list of deltachat.contact.Contact objects for 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

get_subtitle()

return the subtitle of the chat :returns: the subtitle

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”

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

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