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

create a new non persistent message.

Parameters

view_type – a string specifying “text”, “video”, “image”, “audio” or “file”.

Returns

deltachat.message.Message instance.

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.

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.message.Message objects.

create_chat_by_contact(contact)[source]

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

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

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

stop IMAP/SMTP threads.

Contact

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

Delta-Chat Contact.

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

addr

normalized e-mail address for this account.

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

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

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_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 – passed to MessageType.new().

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 with updated state

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.

Exception

ValueError if contact could not be added

Returns

None

remove_contact(contact)[source]

remove a contact from this chat.

Params

contact object.

Exception

ValueError if contact could not be removed

Returns

None

get_contacts()[source]

get all contacts for this chat.

Params

contact object.

Exception

ValueError if contact could not be added

Returns

None

Message

class deltachat.message.Message(dc_context, id)[source]

Message object.

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

classmethod new(dc_context, view_type)[source]

create a non-persistent method.

get_state()[source]

get the message in/out state.

Returns

deltachat.message.MessageState

text

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

set_text(text)[source]

set text of this message.

filename

filename if there was an attachment, otherwise empty string.

set_file(path, mime_type=None)[source]

set file for this message.

basename

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

filemime

mime type of the file (if it exists)

view_type

the view type of this message.

Returns

a deltachat.message.MessageType instance.

time_sent

UTC time when the message was sent.

Returns

naive datetime.datetime() object.

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

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

MessageType

class deltachat.message.MessageType(type)[source]

DeltaChat message type, with is_* methods.

name

human readable type name.

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.

MessageState

class deltachat.message.MessageState(message)[source]

Current Message In/Out state, updated on each call of is_* methods.

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.