For AI agents: markdown of this page — /docs-content-en/mail/mailboxes/senders.md documentation index — /llms.txt

Mailbox sender addresses

GET /v1/mail/mailboxes/:id/senders

Returns the list of addresses on whose behalf messages can be sent from the given mailbox.

The generic filter parameter is not applied by this endpoint. By default, the API preserves the previous HTTP 200 response and data, adds Warning: 299 - "filter is not supported on this endpoint and was ignored", and records unsupported-filter use in the server log.

Parameters

Parameter In Type Required Default Description
Parameterid Inpath Typenumber Requiredyes Default— DescriptionMailbox identifier (from the mailbox list)

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/mail/mailboxes/1/senders" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/mail/mailboxes/1/senders" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/mail/mailboxes/1/senders', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { success, data } = await res.json()
console.log(data.items)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/mail/mailboxes/1/senders', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.items Typearray DescriptionList of sender addresses
Fielddata.items[].email Typestring DescriptionSender email address
Fielddata.items[].name Typestring DescriptionSender display name
Fielddata.items[].sender Typestring DescriptionString for the From header in the format "Name <email>"

Response example

JSON 
{
  "success": true,
  "data": {
    "items": [
      {
        "email": "info@example.com",
        "name": "Work mail",
        "sender": "Company <info@example.com>"
      },
      {
        "email": "support@example.com",
        "name": "Support",
        "sender": "Support team <support@example.com>"
      },
      {
        "email": "sales@example.com",
        "name": "Sales department",
        "sender": "Sales department <sales@example.com>"
      }
    ]
  }
}

Error response example

400 — non-numeric ID:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "id must be a positive integer"
  }
}

Errors

HTTP Code Description
HTTP200 CodeWarning: 299 DescriptionThe filter is ignored by default; previous data is preserved and the warning is sent in the Warning header.
HTTP400 (strict mode only) CodeUNSUPPORTED_FILTER DescriptionThe server mode is disabled by default; until it is enabled, the endpoint preserves HTTP 200 and the previous data.
HTTP400 CodeINVALID_PARAMS Descriptionid is not a positive integer
HTTP403 CodeSCOPE_DENIED DescriptionAPI key does not have the mail scope
HTTP401 CodeTOKEN_MISSING DescriptionAPI key has no configured tokens
HTTP429 CodeRATE_LIMITED DescriptionRequest limit exceeded
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionThe Bitrix24 portal is unavailable
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error

Full list of common API errors — Errors.

Known specifics

Sending addresses. Call this endpoint before composing a message to get the list of allowed sender addresses and let the user pick the one they need.

See also