high level API reference¶
deltachat.account.Account
(your main entry point, creates the other classes)
Account¶
- class deltachat.account.Account(db_path, os_name=None, logging=True)[source]¶
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.
- set_stock_translation(id: int, string: str) None [source]¶
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: str, value: Optional[str]) None [source]¶
set configuration values.
- Parameters
name – config key name (unicode)
value – value to set (unicode)
- Returns
None
- get_config(name: str) str [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.
- update_config(kwargs: Dict[str, Any]) None [source]¶
update config values.
- Parameters
kwargs – name=value config settings for this account. values need to be unicode.
- Returns
None
- is_configured() bool [source]¶
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: Optional[str]) None [source]¶
Set self avatar.
- Raises
ValueError – if profile image could not be set
- Returns
None
- get_latest_backupfile(backupdir) Optional[str] [source]¶
return the latest backup file in a given directory.
- get_blobdir() str [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() deltachat.contact.Contact [source]¶
return this account’s identity as a
deltachat.contact.Contact
.- Returns
- create_contact(obj, name: Optional[str] = None) deltachat.contact.Contact [source]¶
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: deltachat.contact.Contact) bool [source]¶
delete a Contact.
- Parameters
contact – contact object obtained
- Returns
True if deletion succeeded (contact was deleted)
- get_contact_by_addr(email: str) Optional[deltachat.contact.Contact] [source]¶
get a contact for the email address or None if it’s blocked or doesn’t exist.
- get_contact_by_id(contact_id: int) deltachat.contact.Contact [source]¶
return Contact instance or raise an exception. :param contact_id: integer id of this contact. :returns:
deltachat.contact.Contact
instance.
- get_blocked_contacts() List[deltachat.contact.Contact] [source]¶
return a list of all blocked contacts.
- Returns
list of
deltachat.contact.Contact
objects.
- get_contacts(query: Optional[str] = None, with_self: bool = False, only_verified: bool = False) List[deltachat.contact.Contact] [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.contact.Contact
objects.
- get_fresh_messages() Generator[deltachat.message.Message, None, None] [source]¶
yield all fresh messages from all chats.
- create_chat(obj) deltachat.chat.Chat [source]¶
Create a 1:1 chat with Account, Contact or e-mail address.
- create_group_chat(name: str, contacts: Optional[List[deltachat.contact.Contact]] = None, verified: bool = False) deltachat.chat.Chat [source]¶
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() List[deltachat.chat.Chat] [source]¶
return list of chats.
- Returns
a list of
deltachat.chat.Chat
objects.
- get_message_by_id(msg_id: int) deltachat.message.Message [source]¶
return Message instance. :param msg_id: integer id of this message. :returns:
deltachat.message.Message
instance.
- get_chat_by_id(chat_id: int) deltachat.chat.Chat [source]¶
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: List[Union[int, deltachat.message.Message]]) None [source]¶
mark the given set of messages as seen.
- Parameters
messages – a list of message ids or Message instances.
- forward_messages(messages: List[deltachat.message.Message], chat: deltachat.chat.Chat) None [source]¶
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: List[deltachat.message.Message]) None [source]¶
delete messages (local and remote).
- Parameters
messages – list of
deltachat.message.Message
object.- Returns
None
- export_self_keys(path)[source]¶
export public and private keys to the specified directory.
Note that the account does not have to be started.
- export_all(path)[source]¶
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 has to be stopped; call stop_io() if necessary.
- import_self_keys(path)[source]¶
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)[source]¶
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() str [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() str [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.
- 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.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)[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.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: float = 0.0, longitude: float = 0.0, accuracy: float = 0.0) None [source]¶
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)[source]¶
add an account plugin which implements one or more of the
deltachat.hookspec.PerAccount
hooks.
- start_io()[source]¶
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
- maybe_network()[source]¶
This function should be called when there is a hint that the network is available again, e.g. as a response to system event reporting network availability. The library will try to send pending messages out immediately.
Moreover, to have a reliable state when the app comes to foreground with network available, it may be reasonable to call the function also at that moment.
It is okay to call the function unconditionally when there is network available, however, calling the function _without_ having network may interfere with the backoff algorithm and will led to let the jobs fail faster, with fewer retries and may avoid messages being sent out.
Finally, if the context was created by the dc_accounts_t account manager (currently not implemented in the Python bindings), use dc_accounts_maybe_network() instead of this function
Contact¶
- class deltachat.contact.Contact(account, id)[source]¶
Delta-Chat Contact.
You obtain instances of it through
deltachat.account.Account
.- property addr: str¶
normalized e-mail address for this account.
- property name: str¶
display name for this contact.
- property display_name: str¶
display name for this contact.
- property last_seen: datetime.date¶
Last seen timestamp.
- set_blocked(block=True)[source]¶
[Deprecated, use block/unblock methods] Block or unblock a contact.
- get_profile_image() Optional[str] [source]¶
Get contact profile image.
- Returns
path to profile image, None if no profile image exists.
- property status¶
Get contact status.
- Returns
contact status, empty string if it doesn’t exist.
- create_chat()[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.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)[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() None [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_group() bool [source]¶
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_muted() bool [source]¶
return true if this chat is muted.
- Returns
True if chat is muted, False otherwise.
- is_contact_request()[source]¶
return True if this chat is a contact request chat.
- Returns
True if chat is a contact request 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.
- can_send() bool [source]¶
Check if messages can be sent to a give chat. This is not true eg. for the contact requests or for the device-talk
- Returns
True if the chat is writable, False otherwise
- is_protected() bool [source]¶
return True if this chat is a protected chat.
- Returns
True if chat is protected, False otherwise.
- set_name(name: str) bool [source]¶
set name of this chat.
- Parameters
name – as a unicode string.
- Returns
True on success, False otherwise
- mute(duration: Optional[int] = None) None [source]¶
mutes the chat
- Parameters
duration – Number of seconds to mute the chat for. None to mute until unmuted again.
- Returns
None
- get_mute_duration() int [source]¶
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)
- set_ephemeral_timer(timer: int) bool [source]¶
set ephemeral timer.
- Param
timer value in seconds
- Returns
True on success, False otherwise
- get_encryption_info() Optional[str] [source]¶
Return encryption info for this chat.
- Returns
a string with encryption preferences of all chat members
- get_join_qr() Optional[str] [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_msg(msg: deltachat.message.Message) deltachat.message.Message [source]¶
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()
orprepare_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)[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]¶
prepare a message for sending.
- Parameters
msg – the message to be prepared.
- Returns
a
deltachat.message.Message
instance. This is the same object that was passed in, which has been modified with the new state of the core.
- 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 byprepare_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(obj)[source]¶
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)[source]¶
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()[source]¶
get all contacts for this chat. :returns: list of
deltachat.contact.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.
- is_sending_locations()[source]¶
return True if this chat has location-sending enabled currently. :returns: True if location sending is enabled.
- enable_sending_locations(seconds)[source]¶
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)[source]¶
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)[source]¶
Message object.
You obtain instances of it through
deltachat.account.Account
ordeltachat.chat.Chat
.- classmethod new_empty(account, view_type)[source]¶
create a non-persistent message.
- Param
view_type is the message type code or one of the strings: “text”, “audio”, “video”, “file”, “sticker”
- create_chat()[source]¶
create or get an existing chat (group) object for this message.
If the message is a contact request the sender will become an accepted contact.
- Returns
a
deltachat.chat.Chat
object.
- property id¶
id of this message.
- property text: str¶
unicode text of this messages (might be empty if not a text message).
- property html: str¶
html text of this messages (might be empty if not an html message).
- set_html(html_text)[source]¶
set the html part of this message.
It is possible to have text and html part at the same time.
- property filename¶
filename if there was an attachment, otherwise empty string.
- property basename: str¶
basename of the attachment if it exists, otherwise empty string.
- property filemime: str¶
mime type of the file (if it exists)
- get_message_info() str [source]¶
Return informational text for a single message.
The text is multiline and may contain eg. the raw text of the message.
- 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: Optional[str]¶
Text inside the quote
- Returns
Quoted text
- property quote¶
Quote getter
- Returns
Quoted message, if found in the database
- 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 error: Optional[str]¶
Error message
- property chat¶
chat this message was posted in.
- Returns
deltachat.chat.Chat
object
- property override_sender_name: Optional[str]¶
the name that should be shown over the message instead of the contact display name.
Usually used to impersonate someone else.
- get_sender_chat()[source]¶
return the 1:1 chat with the sender of this message.
- Returns
deltachat.chat.Chat
instance
- get_sender_contact()[source]¶
return the contact of who wrote the message.
- Returns
deltachat.chat.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_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().