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

• deltachat.chatting.Chat

• deltachat.message.Message

• deltachat.message.MessageType

• deltachat.message.MessageState

Account

class deltachat.account.Account(db_path, logid=None)

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

return dictionary of built config parameters.

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.

check_is_configured()

Raise ValueError if this account is not configured.

get_infostring()

return info of the configured account.

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

Returns

deltachat.chatting.Contact

create_message(view_type)

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)

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)

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)

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)

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)

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

return list of chats.

Returns

a list of deltachat.chatting.Chat objects.

get_message_by_id(msg_id)

return Message instance.

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

Returns

None

delete_messages(messages)

delete messages (local and remote).

Parameters

messages – list of deltachat.message.Message object.

Returns

None

start_threads()

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

stop IMAP/SMTP threads.

Contact

class deltachat.chatting.Contact(dc_context, id)

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

Return True if the contact is blocked.

is_verified()

Return True if the contact is verified.

Chat

class deltachat.chatting.Chat(dc_context, 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_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.

get_name()

return name of this chat.

Returns

unicode name

set_name(name)

set name of this chat.

Param

name as a unicode string.

Returns

None

get_type()

return type of this chat.

Returns

one of const.DC_CHAT_TYPE_*

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

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

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(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. :raises ValueError: if contact could not be added :returns: list of deltachat.chatting.Contact objects for this chat

Message

class deltachat.message.Message(dc_context, id)

Message object.

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

classmethod new(dc_context, view_type)

create a non-persistent method.

get_state()

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)

set text of this message.

filename

filename if there was an attachment, otherwise empty string.

set_file(path, mime_type=None)

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

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

return the contact of who wrote the message.

Returns

deltachat.chatting.Contact instance

MessageType

class deltachat.message.MessageType(type)

DeltaChat message type, with is_* methods.

name

human readable type name.

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.

MessageState

class deltachat.message.MessageState(message)

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

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.