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, string)[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, 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.
-
update_config
(kwargs)[source]¶ update config values.
- 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.
-
set_avatar
(img_path)[source]¶ Set self avatar.
- Raises
ValueError – if profile image could not be set
- Returns
None
-
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.contact.Contact
.- Returns
-
create_contact
(obj, name=None)[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)[source]¶ delete a Contact.
- Parameters
contact – contact object obtained
- Returns
True if deletion succeeded (contact was deleted)
-
get_contact_by_addr
(email)[source]¶ get a contact for the email address or None if it’s blocked or doesn’t exist.
-
get_contact_by_id
(contact_id)[source]¶ return Contact instance or None. :param contact_id: integer id of this contact. :returns: None or
deltachat.contact.Contact
instance.
-
get_blocked_contacts
()[source]¶ return a list of all blocked contacts.
- Returns
list of
deltachat.contact.Contact
objects.
-
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.contact.Contact
objects.
-
create_group_chat
(name, contacts=None, verified=False)[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
()[source]¶ return list of chats.
- Returns
a list of
deltachat.chat.Chat
objects.
-
get_message_by_id
(msg_id)[source]¶ return Message instance. :param msg_id: integer id of this message. :returns:
deltachat.message.Message
instance.
-
get_chat_by_id
(chat_id)[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)[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
messages – list of
deltachat.message.Message
object.chat –
deltachat.chat.Chat
object.
- Returns
None
-
delete_messages
(messages)[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 does not have to be started.
-
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
()[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.
-
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=0.0, longitude=0.0, accuracy=0.0)[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
-
exception
Contact¶
-
class
deltachat.contact.
Contact
(account, id)[source]¶ Delta-Chat Contact.
You obtain instances of it through
deltachat.account.Account
.-
property
addr
¶ normalized e-mail address for this account.
-
property
name
¶ display name for this contact.
-
property
display_name
¶ display name for this contact.
-
set_blocked
(block=True)[source]¶ [Deprecated, use block/unblock methods] Block or unblock a contact.
-
get_profile_image
()[source]¶ Get contact profile image.
- Returns
path to profile image, None if no profile image exists.
-
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.
-
property
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
()[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
()[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_deaddrop
()[source]¶ return true if this chat is a deaddrop chat.
- Returns
True if chat is the deaddrop chat, False otherwise.
-
is_muted
()[source]¶ return true if this chat is muted.
- Returns
True if chat is muted, 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
()[source]¶ Check if messages can be sent to a give chat. This is not true eg. for the deaddrop or for the device-talk
- Returns
True if the chat is writable, False otherwise
-
is_protected
()[source]¶ return True if this chat is a protected chat.
- Returns
True if chat is protected, False otherwise.
-
mute
(duration=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
()[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)
-
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_msg
(msg)[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]¶ 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 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 “text”, “audio”, “video”, “file”
-
create_chat
()[source]¶ create or get an existing chat (group) object for this message.
If the message is a deaddrop contact request the sender will become an accepted contact.
- Returns
a
deltachat.chat.Chat
object.
-
property
text
¶ unicode text of this messages (might be empty if not a text message).
-
property
filename
¶ filename if there was an attachment, otherwise empty string.
-
property
basename
¶ basename of the attachment if it exists, otherwise empty string.
-
property
filemime
¶ mime type of the file (if it exists)
-
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.
-
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
¶ 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
¶ Error message
-
property
chat
¶ chat this message was posted in.
- Returns
deltachat.chat.Chat
object
-
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().
-
classmethod