high level API reference

Note

This API is work in progress and may change in versions prior to 1.0.

Account

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

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

get_info()[source]

return dictionary of built config parameters.

set_config(name, value)[source]

set configuration values.

Parameters
  • name – config key name (unicode)

  • value – value to set (unicode)

Returns

None

get_config(name)[source]

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)[source]

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()[source]

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

Returns

True if account is configured.

check_is_configured()[source]

Raise ValueError if this account is not configured.

get_infostring()[source]

return info of the configured account.

get_blobdir()[source]

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()[source]

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

Returns

deltachat.chatting.Contact

create_contact(email, name=None)[source]

create a (new) Contact. If there already is a Contact with that e-mail address, it is unblocked and its name is updated.

Parameters
  • email – email-address (text type)

  • name – display name for this contact (optional)

Returns

deltachat.chatting.Contact instance.

delete_contact(contact)[source]

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)[source]

get a (filtered) list of contacts.

Parameters
  • query – if a string is specified, only return contacts whose name or e-mail matches query.

  • only_verified – if true only return verified contacts.

  • with_self – if true the self-contact is also returned.

Returns

list of deltachat.chatting.Contact objects.

create_chat_by_contact(contact)[source]

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

Parameters

contact – chat_id (int) or contact object.

Returns

a deltachat.chatting.Chat object.

create_chat_by_message(message)[source]

create or get an existing chat object for the the specified message.

Parameters

message – messsage id or message instance.

Returns

a deltachat.chatting.Chat object.

create_group_chat(name, verified=False)[source]

create a new group chat object.

Chats are unpromoted until the first message is sent.

Parameters

verified – if true only verified contacts can be added.

Returns

a deltachat.chatting.Chat object.

get_chats()[source]

return list of chats.

Returns

a list of deltachat.chatting.Chat objects.

get_message_by_id(msg_id)[source]

return Message instance.

mark_seen_messages(messages)[source]

mark the given set of messages as seen.

Parameters

messages – a list of message ids or Message instances.

forward_messages(messages, chat)[source]

Forward list of messages to a chat.

Parameters
Returns

None

delete_messages(messages)[source]

delete messages (local and remote).

Parameters

messages – list of deltachat.message.Message object.

Returns

None

export_to_dir(backupdir)[source]

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

import_from_file(path)[source]

import delta chat state from the specified backup file.

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

initiate_key_transfer()[source]

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()[source]

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)[source]

check qr code and return ScannedQRCode instance representing the result

qr_setup_contact(qr)[source]

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.chatting.Chat instance is returned. :param qr: valid “setup contact” QR code (all other QR codes will result in an exception)

qr_join_chat(qr)[source]

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.chatting.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()[source]

wait for and return next incoming message.

start_threads(mvbox=False, sentbox=False)[source]

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)[source]

stop IMAP/SMTP threads.

shutdown(wait=True)[source]

stop threads and close and remove underlying dc_context and callbacks.

Contact

class deltachat.chatting.Contact(dc_context, id)[source]

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()[source]

Return True if the contact is blocked.

is_verified()[source]

Return True if the contact is verified.

Chat

class deltachat.chatting.Chat(account, id)[source]

Chat object which manages members and through which you can send and retrieve messages.

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

delete()[source]

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()[source]

return true if this chat is a deaddrop chat.

Returns

True if chat is the deaddrop chat, False otherwise.

is_promoted()[source]

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()[source]

return True if this chat is a verified group.

Returns

True if chat is verified, False otherwise.

get_name()[source]

return name of this chat.

Returns

unicode name

set_name(name)[source]

set name of this chat.

Param

name as a unicode string.

Returns

None

get_type()[source]

return type of this chat.

Returns

one of const.DC_CHAT_TYPE_*

get_join_qr()[source]

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_text(text)[source]

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')[source]

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)[source]

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)[source]

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')[source]

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)[source]

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)[source]

set message as draft.

Parameters

message – a Message instance

Returns

None

get_draft()[source]

get draft message for this chat.

Parameters

message – a Message instance

Returns

Message object or None (if no draft available)

get_messages()[source]

return list of messages in this chat.

Returns

list of deltachat.message.Message objects for this chat.

count_fresh_messages()[source]

return number of fresh messages in this chat.

Returns

number of fresh messages

mark_noticed()[source]

mark all messages in this chat as noticed.

Noticed messages are no longer fresh.

add_contact(contact)[source]

add a contact to this chat.

Params

contact object.

Raises

ValueError – if contact could not be added

Returns

None

remove_contact(contact)[source]

remove a contact from this chat.

Params

contact object.

Raises

ValueError – if contact could not be removed

Returns

None

get_contacts()[source]

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

set_profile_image(img_path)[source]

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()[source]

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()[source]

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.

Message

class deltachat.message.Message(account, dc_msg)[source]

Message object.

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

classmethod new_empty(account, view_type)[source]

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)[source]

set text of this message.

property filename

filename if there was an attachment, otherwise empty string.

set_file(path, mime_type=None)[source]

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()[source]

return True if this message is a setup message.

is_encrypted()[source]

return True if this message was encrypted.

get_message_info()[source]

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)[source]

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()[source]

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

get_sender_contact()[source]

return the contact of who wrote the message.

Returns

deltachat.chatting.Contact instance

is_in_fresh()[source]

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()[source]

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()[source]

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()[source]

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

is_out_pending()[source]

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

is_out_failed()[source]

Return True if Message is unrecoverably failed.

is_out_delivered()[source]

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()[source]

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()[source]

return True if it’s a text message.

is_image()[source]

return True if it’s an image message.

is_gif()[source]

return True if it’s a gif message.

is_audio()[source]

return True if it’s an audio message.

is_video()[source]

return True if it’s a video message.

is_file()[source]

return True if it’s a file message.