beA Electronic Mailbox

The beA (besonderer elektronischer Anwaltspostkasten) is a legally mandated electronic mailbox for German lawyers. This API lets you manage beA accounts, send and receive messages, search the beA directory, and handle session lifecycle programmatically.

Endpoints

Account Management

Method	Path	Description
POST	/api/v1/bea/accounts	Connect a beA account (JSON credentials)
POST	/api/v1/bea/accounts/upload	Connect beA account via .p12 certificate upload
POST	/api/v1/bea/accounts/kanzlei	Connect a BAG/Kanzlei postfach
GET	/api/v1/bea/accounts	List all beA accounts for the workspace
GET	/api/v1/bea/accounts/{account_id}	Get a beA account by ID
PATCH	/api/v1/bea/accounts/{account_id}/eda-mahn	Store PVKEZI/Ausbaugrad for EDA-Mahn
DELETE	/api/v1/bea/accounts/{account_id}	Disconnect a beA account

Session & Authentication

Method	Path	Description
POST	/api/v1/bea/auth/login	Login to a beA account
POST	/api/v1/bea/auth/local-login	Login via local beA card/software token
POST	/api/v1/bea/auth/logout/{account_id}	Logout from a beA account
GET	/api/v1/bea/accounts/{account_id}/session	Get current session status

Messages

Method	Path	Description
POST	/api/v1/bea/accounts/{account_id}/sync	Trigger manual message sync
GET	/api/v1/bea/accounts/{account_id}/folders	Get folder structure
GET	/api/v1/bea/messages	List beA messages
GET	/api/v1/bea/messages/{message_id}	Get a beA message
POST	/api/v1/bea/messages/{message_id}/assign	Assign message to party/case

Attachments

Method	Path	Description
GET	/api/v1/bea/messages/{message_id}/attachments	List message attachments
GET	/api/v1/bea/messages/{message_id}/attachments/{id}/download	Download attachment

Drafts

Method	Path	Description
POST	/api/v1/bea/drafts	Create a beA draft
GET	/api/v1/bea/drafts	List beA drafts
GET	/api/v1/bea/drafts/{draft_id}	Get a beA draft
PUT	/api/v1/bea/drafts/{draft_id}	Update a beA draft
DELETE	/api/v1/bea/drafts/{draft_id}	Delete a beA draft
POST	/api/v1/bea/drafts/{draft_id}/send	Send a beA draft

Directory

Method	Path	Description
GET	/api/v1/bea/directory/search	Search beA directory for addressees

Permissions

Method	Path	Description
GET	/api/v1/bea/accounts/{account_id}/administered-postboxes	Get administered postboxes
GET	/api/v1/bea/accounts/{account_id}/permissions	Get beA permissions
POST	/api/v1/bea/permissions	Add beA permissions
DELETE	/api/v1/bea/permissions	Remove beA permissions

Connect a beA Account

POST /api/v1/bea/accounts

{
  "certificate_base64": "BASE64_ENCODED_P12",
  "passphrase": "certificate-passphrase",
  "label": "Dr. Mueller - Kanzlei Mayer"
}

Send a beA Message

The typical send flow is:

1. Create a draft with the recipient, subject, body, and attachments
2. Update the draft if needed (autosave)
3. Send the draft -- this submits it to the beA network

POST /api/v1/bea/drafts

{
  "account_id": "bea_acc_01",
  "to": [
    {
      "name": "Rechtsanwalt Schmidt",
      "bea_id": "DE123456789012345"
    }
  ],
  "subject": "Mandatsbestaetigung",
  "body": "Sehr geehrter Herr Kollege...",
  "attachments": ["doc_01ABCDEF"]
}

Then send:

POST /api/v1/bea/drafts/{draft_id}/send

Search the beA Directory

GET /api/v1/bea/directory/search?q=Schmidt&city=Berlin

Returns matching beA-registered attorneys and notaries:

{
  "results": [
    {
      "bea_id": "DE123456789012345",
      "name": "Rechtsanwalt Dr. Hans Schmidt",
      "firm": "Schmidt & Partner",
      "city": "Berlin",
      "postfach_active": true
    }
  ]
}

Error Responses

Status	Code	Meaning
401	BEA_NOT_AUTHENTICATED	beA session expired or not logged in
403	BEA_ACCOUNT_LOCKED	Account is locked by BRAK
404	BEA_ACCOUNT_NOT_FOUND	Account ID does not exist
422	BEA_CERTIFICATE_INVALID	Certificate is invalid or passphrase is wrong
502	BEA_GATEWAY_ERROR	Upstream beA/BRAK service unavailable

Next Steps

• Email Inbound -- General inbound email
• Email Outbound -- General outbound email
• Parties -- Auto-assign beA messages to parties