Skip to main content
Lerian BC Correios runs one polling worker per tenant. Each cycle asks BC Correio for the folders and the mail of the tenant’s Sisbacen user, and stores what is new.

​
Polling cycle

Each cycle runs these steps:
  1. Lists the BC Correio folders that the Sisbacen user can see.
  2. Reads each folder page by page, until a page comes back empty.
  3. Reads each new mail and fetches its attachments, then stores them.
  4. For a mail that it already stores, fetches the attachments that failed in an earlier cycle.
An error on one folder or one mail does not stop the cycle. The next cycle tries that work again.

​
Folders

When Lerian BC Correios stores a new mail, it puts the mail in the local folder that matches its BC Correio folder: A later move of the mail in BC Correio does not change its local folder. You cannot restore a mail from CANCELLED.

​
Initial synchronization

The first cycle of a tenant stores the mail that already exists in BC Correio. Lerian BC Correios does not send that backlog to the AI provider. You can still ask for an analysis of a mail from it. A cycle that fails to read a folder does not complete the initial synchronization. The next cycle runs it again.

​
Storing mail and attachments

Lerian BC Correios stores each mail in PostgreSQL. It stores attachments in S3-compatible object storage or on the local filesystem, with the SHA-256 checksum of each file. When you download an attachment, the service checks the file against its checksum.

​
Sending a message

POST /mails/send sends a text message to a BACEN department through BC Correio. The message goes to the destination in the request. Without one, it goes to the default destination of the tenant. Without both, it goes to DEINF. The tenant needs stored BC Correio credentials. Without them, the request returns 401 BCC-2001, and Lerian BC Correios stores nothing. Lerian BC Correios records the message as PENDING before it calls BC Correio. The outcome then decides the status and the answer: A repeat of the request with the same X-Idempotency key does not send the message again. While the first request runs, the repeat can return 409 BCC-0012 with a Retry-After header. Otherwise the stored status of the first request decides the answer: TRANSMISSION_PENDING_GRACE_SEC sets the grace window, 30 seconds by default. Do not send a message again after BCC-2010. BC Correio can already hold it. Confirm with BACEN through its manual channel that the message did not arrive, and only then send it with a new key. Lerian BC Correios does not retry a send by itself.

​
Local mail actions

Mark as read, archive, and restore change your local copy of a mail. Lerian BC Correios does not send these actions to BC Correio. A restore of a mail in the CANCELLED or SENT folder returns 409 BCC-0014.

​
AI insight

A tenant can configure an AI provider: openai, anthropic, or gemini, with its own API key. Lerian BC Correios sends the mail body to that provider, together with the text it extracts from TXT, CSV, XML, PDF, and DOCX attachments. When automatic AI analysis is enabled and the tenant has configured an AI provider, Lerian BC Correios analyzes a mail with no attachments and a body of at least AI_BODY_INLINE_THRESHOLD in the polling cycle. A background worker analyzes the other mail. POST /mails/{id}/reanalyze waits up to 20 seconds for the analysis. A successful completion returns 200 with the insight. If the analysis is still running at that deadline, it returns 202 with a pending status; poll GET /mails/{id}/ai-status for the result.

​
Retention

Each tenant sets a retention period between 1825 and 36500 days in its settings. A retention worker runs once every 24 hours. For mail that passes the retention period, it deletes the attachment files from storage and hides the mail. It then deletes the mail records from the database.

​
Audit trail

The audit trail records these actions: GET /audit lists the entries. GET /audit/export exports them as CSV. Send Accept: application/pdf to get a PDF.