API Reference

Delta Chat JSON-RPC high-level API.

class deltachat_rpc_client.Account(manager: DeltaChat, id: int)

Delta Chat account.

wait_for_event(event_type=None) → AttrDict

Wait until the next event and return it.

clear_all_events()

Remove all queued-up events for a given account.

Useful for tests.

remove() → None

Remove the account.

clone() → Account

Clone given account.

This uses backup-transfer via iroh, i.e. the ‘Add second device’ feature.

start_io() → None

Start the account I/O.

stop_io() → None

Stop the account I/O.

get_info() → AttrDict

Return dictionary of this account configuration parameters.

get_size() → int

Get the combined filesize of an account in bytes.

is_configured() → bool

Return True if this account is configured.

set_config(key: str, value: str | None = None) → None

Set configuration value.

get_config(key: str) → str | None

Get configuration value.

update_config(**kwargs) → None

Update config values.

set_avatar(img_path: str | None = None) → None

Set self avatar.

Passing None will discard the currently set avatar.

get_avatar() → str | None

Get self avatar.

check_qr(qr)

Parse QR code contents.

This function takes the raw text scanned and checks what can be done with it.

set_config_from_qr(qr: str)

Set configuration values from a QR code.

configure()

Configure an account.

add_or_update_transport(params)

Add a new transport.

add_transport_from_qr(qr: str)

Add a new transport using a QR code.

delete_transport(addr: str)

Delete a transport.

list_transports()

Return the list of all email accounts that are used as a transport in the current profile.

bring_online()

Start I/O and wait until IMAP becomes IDLE.

create_contact(obj: int | str | Contact | Account, name: str | None = None) → Contact

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, contact id or account.

• name – (optional) display name for this contact.

make_vcard(contacts: list[Contact]) → str

Create vCard with the given contacts.

import_vcard(vcard: str) → list[Contact]

Import vCard.

Return created or modified contacts in the order they appear in vCard.

create_chat(account: Account) → Chat

Create a 1:1 chat with another account.

get_device_chat() → Chat

Return device chat.

get_contact_by_id(contact_id: int) → Contact

Return Contact instance for the given contact ID.

get_contact_by_addr(address: str) → Contact | None

Looks up a known and unblocked contact with a given e-mail address. To get a list of all known and unblocked contacts, use contacts_get_contacts().

POTENTIAL SECURITY ISSUE: If there are multiple contacts with this address (e.g. an address-contact and a key-contact), this looks up the most recently seen contact, i.e. which contact is returned depends on which contact last sent a message. If the user just clicked on a mailto: link, then this is the best thing you can do. But DO NOT internally represent contacts by their email address and do not use this function to look them up; otherwise this function will sometimes look up the wrong contact. Instead, you should internally represent contacts by their ids.

To validate an e-mail address independently of the contact database use check_email_validity().

get_blocked_contacts() → list[AttrDict]

Return a list with snapshots of all blocked contacts.

get_chat_by_contact(contact: int | Contact) → Chat | None

Return 1:1 chat for a contact if it exists.

get_contacts(query: str | None = None, *, with_self: bool = False, snapshot: bool = False) → list[Contact] | list[AttrDict]

Get a filtered list of contacts.

Parameters:

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

• with_self – if True the self-contact is also included if it matches the query.

• snapshot – If True return a list of contact snapshots instead of Contact instances.

property self_contact: Contact

Account’s identity as a Contact.

property device_contact: Chat

Account’s device contact.

get_chatlist(query: str | None = None, contact: Contact | None = None, archived_only: bool = False, for_forwarding: bool = False, no_specials: bool = False, alldone_hint: bool = False, snapshot: bool = False) → list[Chat] | list[AttrDict]

Return list of chats.

Parameters:

• query – if a string is specified only chats matching this query are returned.

• contact – if a contact is specified only chats including this contact are returned.

• archived_only – if True only archived chats are returned.

• for_forwarding – if True the chat list is sorted with “Saved messages” at the top and without “Device chat” and contact requests.

• no_specials – if True archive link is not added to the list.

• alldone_hint – if True the “all done hint” special chat will be added to the list as needed.

• snapshot – If True return a list of chat snapshots instead of Chat instances.

create_group(name: str) → Chat

Create a new group chat.

After creation, the group has only self-contact as member one member (see SpecialContactId.SELF) and is in _unpromoted_ state. This means, you can add or remove members, change the name, the group image and so on without messages being sent to all group members.

This changes as soon as the first message is sent to the group members and the group becomes _promoted_. After that, all changes are synced with all group members by sending status message.

To check, if a chat is still unpromoted, you can look at the is_unpromoted property of a chat (see get_full_snapshot() / get_basic_snapshot()). This may be useful if you want to show some help for just created groups.

create_broadcast(name: str) → Chat

Create a new, outgoing broadcast channel (called “Channel” in the UI).

Broadcast channels are similar to groups on the sending device, however, recipients get the messages in a read-only chat and will not see who the other members are.

Called broadcast here rather than channel, because the word “channel” already appears a lot in the code, which would make it hard to grep for it.

Returns the created chat.

get_chat_by_id(chat_id: int) → Chat

Return the Chat instance with the given ID.

secure_join(qrdata: str) → Chat

Continue a Setup-Contact or Verified-Group-Invite protocol started on another device.

The function returns immediately and the handshake runs in background, sending and receiving several messages. Subsequent calls of secure_join() will abort previous, unfinished handshakes. See https://securejoin.delta.chat/ for protocol details.

Parameters:

qrdata – The text of the scanned QR code.

get_qr_code() → str

Get Setup-Contact QR Code text.

This data needs to be transferred to another Delta Chat account in a second channel, typically used by mobiles with QRcode-show + scan UX.

get_qr_code_svg() → tuple[str, str]

Get Setup-Contact QR code text and SVG.

get_message_by_id(msg_id: int) → Message

Return the Message instance with the given ID.

mark_seen_messages(messages: list[Message]) → None

Mark the given set of messages as seen.

delete_messages(messages: list[Message]) → None

Delete messages (local and remote).

get_fresh_messages() → list[Message]

Return the list of fresh messages, newest messages first.

This call is intended for displaying notifications. If you are writing a bot, process “incoming message” events instead.

get_next_messages() → list[Message]

Return a list of next messages.

wait_next_messages() → list[Message]

(deprecated) Wait for new messages and return a list of them. Meant for bots.

Deprecated 2026-04: This returns the message’s id as soon as the first part arrives, even if it is not fully downloaded yet. The bot needs to wait for the message to be fully downloaded. Since this is usually not the desired behavior, bots should instead use the EventType.INCOMING_MSG event for getting notified about new messages.

wait_for_incoming_msg_event()

Wait for incoming message event and return it.

wait_for_msgs_changed_event()

Wait for messages changed event and return it.

wait_for_msgs_noticed_event()

Wait for messages noticed event and return it.

wait_for_msg(event_type) → Message

Wait for an event about the message.

Consumes all events before the matching event. Returns a message corresponding to the msg_id field of the event.

wait_for_incoming_msg()

Wait for incoming message and return it.

Consumes all events before the next incoming message event.

wait_for_securejoin_inviter_success()

Wait until SecureJoin process finishes successfully on the inviter side.

wait_for_securejoin_joiner_success()

Wait until SecureJoin process finishes successfully on the joiner side.

wait_for_reactions_changed()

Wait for reaction change event.

export_backup(path, passphrase: str = '') → None

Export backup.

import_backup(path, passphrase: str = '') → None

Import backup.

export_self_keys(path) → None

Export keys.

import_self_keys(path) → None

Import keys.

ice_servers() → list

Return ICE servers for WebRTC configuration.

is_sending_locations() → bool

Return True if sending locations to any chat.

class deltachat_rpc_client.AttrDict(*args, **kwargs)

Dictionary that allows accessing values using the “dot notation” as attributes.

class deltachat_rpc_client.Bot(account: Account, hooks: Iterable[tuple[Callable, type | EventFilter]] | None = None, logger: logging.Logger | None = None)

Simple bot implementation that listens to events of a single account.

configure(email: str, password: str, **kwargs) → None

Configure the bot.

class deltachat_rpc_client.Chat(account: Account, id: int)

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

delete() → None

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

block() → None

Block this chat.

accept() → None

Accept this contact request chat.

leave() → None

Leave this chat.

mute(duration: int | None = None) → None

Mute this chat, if a duration is not provided the chat is muted forever.

Parameters:

duration – mute duration from now in seconds. Must be greater than zero.

unmute() → None

Unmute this chat.

pin() → None

Pin this chat.

unpin() → None

Unpin this chat.

archive() → None

Archive this chat.

unarchive() → None

Unarchive this chat.

set_name(name: str) → None

Set name of this chat.

set_ephemeral_timer(timer: int) → None

Set ephemeral timer of this chat in seconds.

0 means the timer is disabled, use 1 for immediate deletion.

get_encryption_info() → str

Return encryption info for this chat.

get_qr_code() → str

Get Join-Group QR code text.

get_qr_code_svg() → tuple[str, str]

Get Join-Group QR code text and SVG data.

get_basic_snapshot() → AttrDict

Get a chat snapshot with basic info about this chat.

get_full_snapshot() → AttrDict

Get a full snapshot of this chat.

can_send() → bool

Return true if messages can be sent to the chat.

send_message(text: str | None = None, html: str | None = None, viewtype: ViewType | None = None, file: str | None = None, filename: str | None = None, location: tuple[float, float] | None = None, override_sender_name: str | None = None, quoted_msg: int | Message | None = None) → Message

Send a message and return the resulting Message instance.

send_text(text: str) → Message

Send a text message and return the resulting Message instance.

send_file(path)

Send a file and return the resulting Message instance.

send_videochat_invitation() → Message

Send a videochat invitation and return the resulting Message instance.

send_sticker(path: str) → Message

Deprecated as of 2026-04; use send_message with Viewtype.STICKER instead.

resend_messages(messages: list[Message]) → None

Resend a list of messages to this chat.

forward_messages(messages: list[Message]) → None

Forward a list of messages to this chat.

set_draft(text: str | None = None, file: str | None = None, filename: str | None = None, quoted_msg: int | None = None, viewtype: str | None = None) → None

Set draft message.

remove_draft() → None

Remove draft message.

get_draft() → AttrDict | None

Get draft message.

get_messages(add_daymarker: bool = False) → list[Message]

Get the list of messages in this chat.

get_fresh_message_count() → int

Get number of fresh messages in this chat.

mark_noticed() → None

Mark all messages in this chat as noticed.

mark_fresh() → None

Mark the last incoming message in the chat as fresh.

add_contact(*contact: int | str | Contact | 'Account') → None

Add contacts to this group.

remove_contact(*contact: int | str | Contact | 'Account') → None

Remove members from this group.

get_contacts() → list[Contact]

Get the contacts belonging to this chat.

For single/direct chats self-address is not included.

num_contacts() → int

Return number of contacts in this chat.

get_past_contacts() → list[Contact]

Get past contacts for this chat.

set_image(path: str) → None

Set profile image of this chat.

Parameters:

path – Full path of the image to use as the group image.

remove_image() → None

Remove profile image of this chat.

send_locations(seconds) → None

Enable location streaming in the chat for the given number of seconds.

Pass 0 to disable location streaming.

is_sending_locations() → bool

Return True if sending locations to this chat.

get_locations(contact: Contact | None = None, timestamp_from: 'datetime' | None = None, timestamp_to: 'datetime' | None = None) → list[AttrDict]

Get list of location snapshots for the given contact in the given timespan.

send_contact(contact: Contact)

Send contact to the chat.

place_outgoing_call(place_call_info: str, has_video_initially: bool) → Message

Starts an outgoing call.

class deltachat_rpc_client.Client(account: Account, hooks: Iterable[tuple[Callable, type | EventFilter]] | None = None, logger: logging.Logger | None = None)

Simple Delta Chat client that listen to events of a single account.

add_hooks(hooks: Iterable[tuple[Callable, type | EventFilter]]) → None

Register multiple hooks.

add_hook(hook: Callable, event: type | EventFilter = <class 'deltachat_rpc_client.events.RawEvent'>) → None

Register hook for the given event filter.

remove_hook(hook: Callable, event: type | EventFilter) → None

Unregister hook from the given event filter.

is_configured() → bool

Return True if the client is configured.

configure(email: str, password: str, **kwargs) → None

Configure the client.

run_forever() → None

Process events forever.

run_until(func: Callable[[AttrDict], bool]) → AttrDict

Start the event processing loop.

class deltachat_rpc_client.Contact(account: Account, id: int)

Contact API.

Essentially a wrapper for RPC, account ID and a contact ID.

block() → None

Block contact.

unblock() → None

Unblock contact.

delete() → None

Delete contact.

set_name(name: str) → None

Change the name of this contact.

get_encryption_info() → str

Get a multi-line encryption info.

Encryption info contains your fingerprint and the fingerprint of the contact.

get_snapshot() → AttrDict

Return a dictionary with a snapshot of all contact properties.

create_chat() → Chat

Create or get an existing 1:1 chat for this contact.

make_vcard() → str

Make a vCard for the contact.

class deltachat_rpc_client.DeltaChat(rpc: Rpc)

Delta Chat accounts manager.

This is the root of the object oriented API.

add_account() → Account

Create a new account database.

get_all_accounts() → list[Account]

Return a list of all available accounts.

start_io() → None

Start the I/O of all accounts.

stop_io() → None

Stop the I/O of all accounts.

background_fetch(timeout_in_seconds: int) → None

Run background fetch for all accounts.

stop_background_fetch() → None

Stop ongoing background fetch.

maybe_network() → None

Indicate that the network conditions might have changed.

get_system_info() → AttrDict

Get information about the Delta Chat core in this system.

set_translations(translations: dict[str, str]) → None

Set stock translation strings.

set_location(latitude, longitude, accuracy) → bool

Set location, return True if location streaming should continue.

stop_sending_locations() → None

Stop sending locations to all chats.

class deltachat_rpc_client.EventType(*values)

Core event types.

exception deltachat_rpc_client.JsonRpcError

JSON-RPC error.

class deltachat_rpc_client.Message(account: Account, id: int)

Delta Chat Message object.

send_reaction(*reaction: str) → Message

Sends a reaction to message.

A reaction is a string that represents an emoji. You can call this function again to change the emoji; the last sent reaction overrides all previously sent reactions. It is possible to remove the reaction by sending an empty string.

get_snapshot() → AttrDict

Get a snapshot with the properties of this message.

get_read_receipts() → List[AttrDict]

Get message read receipts.

get_read_receipt_count() → int

Returns count of read receipts on message.

This view count is meant as a feedback measure for the channel owner only.

get_reactions() → AttrDict | None

Get message reactions.

get_sender_contact() → Contact

Return sender contact.

mark_seen() → None

Mark the message as seen.

exists() → bool

Return True if the message exists.

send_webxdc_status_update(update: dict | str, description: str) → None

Send a webxdc status update. This message must be a webxdc.

get_webxdc_status_updates(last_known_serial: int = 0) → list

Return a list of Webxdc status updates for Webxdc instance message.

get_info() → str

Return message info.

get_webxdc_info() → dict

Get info from a Webxdc message in JSON format.

wait_until_delivered() → None

Consume events until the message is delivered.

resend() → None

Resend messages and make information available for newly added chat members. Resending sends out the original message, however, recipients and webxdc-status may differ. Clients that already have the original message can still ignore the resent message as they have tracked the state by dedicated updates.

Some messages cannot be resent, eg. info-messages, drafts, already pending messages, or messages that are not sent by SELF.

send_webxdc_realtime_advertisement()

Send an advertisement to join the realtime channel.

send_webxdc_realtime_data(data) → None

Send data to the realtime channel.

accept_incoming_call(accept_call_info)

Accepts an incoming call.

end_call()

Ends incoming or outgoing call.

get_call_info() → AttrDict

Return information about the call.

class deltachat_rpc_client.SpecialContactId(*values)

Special contact IDs.

class deltachat_rpc_client.Rpc(accounts_dir: str | None = None, rpc_server_path='deltachat-rpc-server', **kwargs)

RPC client.

start() → None

Start RPC server subprocess and wait for successful initialization.

This method blocks until the RPC server responds to an initial health-check RPC call (get_system_info). If the server fails to start (e.g., due to an invalid accounts directory), a JsonRpcError is raised.

close() → None

Terminate RPC server process and wait until the reader loop finishes.

reader_loop() → None

Process JSON-RPC responses from the RPC server process output.

writer_loop() → None

Writer loop ensuring only a single thread writes requests.

get_queue(account_id: int) → Queue

Get event queue corresponding to the given account ID.

events_loop() → None

Request new events and distributes them between queues.

wait_for_event(account_id: int) → dict | None

Wait for the next event from the given account and returns it.

clear_all_events(account_id: int)

Remove all queued-up events for a given account. Useful for tests.

deltachat_rpc_client.run_bot_cli(until: ~typing.Callable[[~deltachat_rpc_client._utils.AttrDict], bool] = <function _forever>, hooks: ~typing.Iterable[~typing.Tuple[~typing.Callable, type | EventFilter]] | None = None, argv: list | None = None, **kwargs) → None

Run a simple bot command line using the given hooks.

Extra keyword arguments are passed to the internal Rpc object.

deltachat_rpc_client.run_client_cli(hooks: ~typing.Iterable[~typing.Tuple[~typing.Callable, type | EventFilter]] | None = None, until: ~typing.Callable[[~deltachat_rpc_client._utils.AttrDict], bool] = <function _forever>, argv: list | None = None, **kwargs) → None

Run a simple command line app, using the given hooks.

Extra keyword arguments are passed to the internal Rpc object.