Письма (tbank.mails)

Внутренняя переписка H2H (host-to-host): отправка входящих писем, отметка сообщений о прочтении и получение непрочитанных писем.

• Хост: secured-openapi.tbank.ru (mTLS, cert). Отправка входящего письма дополнительно подписывается (signature=HttpSignature(key_id, secret)); остальное — по Bearer.

• Клиенты: tbank.mails.MailsClient (async) и tbank.mails.sync.MailsClient (sync).

from tbank.mails import MailsClient, HttpSignature
from tbank.mails.models import IncomingMailRequest, MarkReadRequest

client = MailsClient(
    token="business-token",
    cert=("client.pem", "client-key.pem"),
    signature=HttpSignature("key-id", "secret"),   # для входящих писем
)

# отправить входящее письмо (mTLS + подпись)
await client.push_incoming_mail(IncomingMailRequest(
    external_id="EXT-1", theme_code="TAX", theme="Вопрос по НДС",
    created_at="2026-06-01T10:00:00Z", text="Здравствуйте!",
))

# непрочитанные письма и отметка о прочтении
unread = await client.list_unread()
ids = [m.id for mail in unread for m in mail.messages if m.is_unread]
await client.mark_read(MarkReadRequest(messages_ids=ids))

Клиент

class tbank.mails.aio.MailsClient(token, *, signature=None, base_url=None, sandbox=False, cert=None, verify=True, retry=None, transport=None)

Базовые классы: BaseAsyncClient

Асинхронный клиент внутренних писем (H2H): входящие письма, отметка о прочтении, непрочитанные письма.

Домен работает на secured-хосте (mTLS, cert). Отправка входящего письма дополнительно подписывается (signature — HttpSignature(keyId, secret)); остальные методы — по Bearer. Провод — camelCase.

Параметры:

• token (str)

• signature (Optional[HttpSignature])

• base_url (Optional[str])

• sandbox (bool)

• cert (Optional[CertTypes])

• verify (VerifyTypes)

• retry (Optional[RetryPolicy])

• transport (Optional[AsyncTransport])

async push_incoming_mail(request)

Отправить входящее письмо (mTLS + подпись).

Параметры:

request (IncomingMailRequest)

Тип результата:

IncomingMailResult

async mark_read(request)

Отметить сообщения как прочитанные.

Параметры:

request (MarkReadRequest)

Тип результата:

None

async list_unread()

Непрочитанные письма со списком сообщений.

Тип результата:

List[Mail]

Модели

class tbank.mails.models.MailModel

Базовые классы: BaseModel

Базовая модель домена: snake_case в Python, camelCase на проводе.

model_config = {'alias_generator': <function to_camel>, 'extra': 'ignore', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tbank.mails.models.IncomingMailRequest(*, externalId, themeCode, theme, createdAt, text=None, files=None)

Базовые классы: MailModel

Входящее письмо (H2H). Требуется text либо files.

Параметры:

• externalId (str)

• themeCode (str)

• theme (str)

• createdAt (datetime)

• text (str | None)

• files (List[str] | None)

model_config = {'alias_generator': <function to_camel>, 'extra': 'ignore', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tbank.mails.models.IncomingMailResult(*, id)

Базовые классы: MailModel

Параметры:

id (str)

model_config = {'alias_generator': <function to_camel>, 'extra': 'ignore', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tbank.mails.models.MarkReadRequest(*, messagesIds)

Базовые классы: MailModel

Параметры:

messagesIds (List[str])

model_config = {'alias_generator': <function to_camel>, 'extra': 'ignore', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tbank.mails.models.MailMessage(*, id, mailId, isFromBank, isUnread, createdAt, text=None, files=None)

Базовые классы: MailModel

Параметры:

• id (str)

• mailId (str)

• isFromBank (bool)

• isUnread (bool)

• createdAt (datetime)

• text (str | None)

• files (List[str] | None)

model_config = {'alias_generator': <function to_camel>, 'extra': 'ignore', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class tbank.mails.models.Mail(*, id, number, companyId, isFromBank, theme, themeCode, status, updatedAt, messages=<factory>, externalId=None)

Базовые классы: MailModel

Письмо со списком сообщений.

Параметры:

• id (str)

• number (int)

• companyId (str)

• isFromBank (bool)

• theme (str)

• themeCode (str)

• status (str)

• updatedAt (datetime)

• messages (List[MailMessage])

• externalId (str | None)

model_config = {'alias_generator': <function to_camel>, 'extra': 'ignore', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].