Blocked Contacts

Block phone numbers, WhatsApp identifiers, or email addresses across your account. Once blocked, inbound messages from the identifier are dropped before persistence (no session or contact creation, no AI processing, no webhook forwarding, no push notifications, no WebSocket broadcast). Outbound sends to a blocked identifier are rejected with HTTP 403.

Authentication

All Blocked Contacts endpoints accept API token authentication via the Authorization header. See Authentication for token generation details.

Block a Contact

Adds an identifier to the account-level block list.

POST /blocked-contacts/{identifierValue}

Path Parameter	Description
identifierValue	URL-encoded identifier to block. Phone numbers normalize to digits-only; emails normalize to lowercase-trim before storage.

Request Body

Optional JSON body with audit metadata:

Field	Type	Required	Description
contactId	string	No	CRM contact ID to associate with the block record
channelId	string	No	Channel ID from which the block action was initiated
sourceSessionId	string	No	Session ID that triggered the block (for audit purposes)

Example Request

curl -X POST "https://api.maiacompany.io/blocked-contacts/%2B5511999991234" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channelId": "ch_abc123"}'

Response

Returns 201 Created when the identifier is newly blocked, or 200 OK when the identifier was already on the block list (idempotent). The original blockedAt timestamp is preserved on re-block.

{
  "identifierValue": "5511999991234",
  "blockedAt": 1714000000000,
  "alreadyBlocked": false
}

Field	Type	Description
identifierValue	string	The normalized identifier that was blocked
blockedAt	number	Unix timestamp (ms) when the block was first created
alreadyBlocked	boolean	true if the identifier was already blocked before this call

Unblock a Contact

Removes an identifier from the account-level block list.

DELETE /blocked-contacts/{identifierValue}

Path Parameter	Description
identifierValue	URL-encoded identifier to unblock

Example Request

curl -X DELETE "https://api.maiacompany.io/blocked-contacts/%2B5511999991234" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

Returns 200 OK (always, idempotent):

{ "unblocked": true }

"unblocked": false is returned when the identifier was not on the block list at the time of the request.

List Blocked Contacts

Returns all blocked identifiers for the account.

GET /blocked-contacts

Example Request

curl "https://api.maiacompany.io/blocked-contacts" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

Returns 200 OK:

{
  "items": [
    {
      "identifierValue": "5511999991234",
      "contactId": "con_xyz",
      "channelId": "ch_abc",
      "sourceSessionId": "5511999991234",
      "blockedBy": "user_abc",
      "blockedAt": 1714000000000
    }
  ]
}

Field	Type	Description
identifierValue	string	The normalized blocked identifier
contactId	string	CRM contact ID associated with the block (if provided at block time)
channelId	string	Channel from which the block was initiated (if provided)
sourceSessionId	string	Session that triggered the block (if provided)
blockedBy	string	ID of the user or system that created the block
blockedAt	number	Unix timestamp (ms) when the block was created

The response is unpaginated. Block lists are account-scoped and naturally bounded.

Error Response: Blocked Contact on Send

When an outbound send targets a blocked identifier, every send endpoint returns HTTP 403 with the standard error envelope:

POST /channels/{channelId}/sessions/{sessionId}/messages  →  403 Forbidden

{
  "error": {
    "code": "CONTACT_BLOCKED",
    "message": "Contact 5511999991234 is blocked for account acc_xyz"
  },
  "requestId": "abc-123",
  "timestamp": "2026-04-27T10:00:00.000Z"
}

API consumers should narrow on body.error.code === 'CONTACT_BLOCKED' to handle this case distinctly from other 403 responses.

Notes

Block scope — Blocks are account-wide. A single block on (accountId, identifierValue) rejects messages across every channel of the account.

Identifier normalization — Phone numbers are normalized to digits-only; emails are lowercased and trimmed before storage and lookup. A block on +55 11 99999-1234 matches an inbound message from 5511999991234.

Idempotency — Re-blocking an already-blocked identifier returns 200 with alreadyBlocked: true. The original blockedAt timestamp is preserved. Unblocking a non-blocked identifier returns 200 with unblocked: false.

Inbound message handling — Inbound messages from a blocked identifier are silently dropped before any processing: no contact creation, no session creation, no message persistence, no AI processing, no webhook forwarding, no push notifications, and no WebSocket broadcast.