Email accounts

A Fakturnia account can e-mail documents from the owner's own mailbox instead of the system address. Mailboxes are connected in the app (Other → Email accounts): SMTP with a password, or Gmail and Outlook through OAuth. Through the API you can check which mailboxes are connected and in what state. That is all: connecting, verifying and editing happen only in the app, because they need a password or an OAuth consent that an integration should not hold.

Why an integration reads this: to know which address invoices are sent from (for a shop footer, say), to warn the user when the default mailbox failed verification, or to show the configuration state in an integration dashboard.

Endpoints#

curl -s https://sandbox.api.fakturnia.pl/external/v1/email-accounts \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "data": {
    "emailAccounts": [
      {
        "id": "681a3b2c4d5e6f7a8b9c0d1e",
        "provider": "gmail",
        "isOAuth": true,
        "email": "biuro@firma.pl",
        "host": null,
        "port": null,
        "secure": true,
        "verificationStatus": "verified",
        "isVerified": 1,
        "isDefault": true,
        "lastError": null,
        "lastVerifiedAt": "2026-09-20T10:00:00.000Z",
        "createdAt": "2026-09-01T10:00:00.000Z",
        "updatedAt": "2026-09-20T10:00:00.000Z"
      },
      {
        "id": "681a3b2c4d5e6f7a8b9c0d1f",
        "provider": "smtp",
        "isOAuth": false,
        "email": "faktury@firma.pl",
        "host": "smtp.firma.pl",
        "port": 465,
        "secure": true,
        "verificationStatus": "error",
        "isVerified": 2,
        "isDefault": false,
        "lastError": "535 Authentication failed",
        "lastVerifiedAt": "2026-08-30T08:12:00.000Z",
        "createdAt": "2026-08-30T08:00:00.000Z",
        "updatedAt": "2026-09-25T06:40:00.000Z"
      }
    ]
  },
  "executionTime": 6
}

Fields#

Secrets (the SMTP password, OAuth tokens) are never returned, not even in the details of a single mailbox.

What happens when a mailbox fails#

When a send from the own mailbox fails, Fakturnia marks it error and the document goes out from the system address, so the recipient still gets the invoice. The user has to fix the configuration in the app, though. If your integration shows mailbox states, watch for verificationStatus === 'error' on the mailbox with isDefault: true.

Errors#