Block Lists
REST API reference for block lists
This reference is generated from the Invitebase OpenAPI contract.
Per-app lists of emails, email domains, devices, and referrer accounts that stop being attributed at ingestion, merged with the disposable-email domain list Invitebase maintains centrally.
List block list entries
The app's own block list. The centrally maintained disposable-email domain list is not included: it is enforced on every app and is not the customer's to edit.
Authentication
Authorization: Bearer <secret key>.
Parameters
| Name | In | Required | Schema | Description |
|---|---|---|---|---|
limit | query | No | {"type":"integer","minimum":1,"maximum":100,"default":25} | |
starting_after | query | No | {"type":"string"} | A cursor (object id) for pagination; returns the page after this object. |
kind | query | No | {"$ref":"#/components/schemas/BlocklistKind"} |
Responses
200
A paginated list of block list entries.
application/json schema:
{
"allOf": [
{
"$ref": "#/components/schemas/ListResponse"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BlocklistEntry"
}
}
}
}
]
}400
The request was malformed or invalid.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}401
Missing or invalid API key.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}403
The API key is valid but is not permitted to call this endpoint.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}429
Too many requests.
Response headers:
{
"Retry-After": {
"description": "Seconds until the caller may retry.",
"schema": {
"type": "integer",
"minimum": 1
}
}
}application/json schema:
{
"$ref": "#/components/schemas/Error"
}Add block list entries
Add up to 100 entries at once. Idempotent by normalized value: Bad+1@Gmail.com and bad@gmail.com are one mailbox, so re-adding one returns the existing entry instead of failing. Entries take effect immediately — the next event that would attribute a blocked identity is refused, and the attempt is recorded.
Authentication
Authorization: Bearer <secret key>.
Parameters
| Name | In | Required | Schema | Description |
|---|---|---|---|---|
Idempotency-Key | header | No | {"type":"string"} | A unique key for one logical mutation. The same key and request replay the original result for 24 hours; using the key with a different request returns 409. |
Request body
Required.
application/json schema:
{
"$ref": "#/components/schemas/BlocklistEntriesCreate"
}Responses
201
The entries now on the list.
application/json schema:
{
"allOf": [
{
"$ref": "#/components/schemas/ListResponse"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BlocklistEntry"
}
}
}
}
]
}400
The request was malformed or invalid.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}401
Missing or invalid API key.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}403
The API key is valid but is not permitted to call this endpoint.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}429
Too many requests.
Response headers:
{
"Retry-After": {
"description": "Seconds until the caller may retry.",
"schema": {
"type": "integer",
"minimum": 1
}
}
}application/json schema:
{
"$ref": "#/components/schemas/Error"
}Remove a block list entry
Authentication
Authorization: Bearer <secret key>.
Parameters
| Name | In | Required | Schema | Description |
|---|---|---|---|---|
entryId | path | Yes | {"type":"string"} |
Responses
200
The entry was removed.
application/json schema:
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "blocklist_entry"
},
"deleted": {
"type": "boolean",
"const": true
}
}
}401
Missing or invalid API key.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}403
The API key is valid but is not permitted to call this endpoint.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}404
The requested resource does not exist.
application/json schema:
{
"$ref": "#/components/schemas/Error"
}429
Too many requests.
Response headers:
{
"Retry-After": {
"description": "Seconds until the caller may retry.",
"schema": {
"type": "integer",
"minimum": 1
}
}
}application/json schema:
{
"$ref": "#/components/schemas/Error"
}Schemas
Schema references below resolve against these definitions. Required fields, enums, bounds, and composed types are preserved from the contract.
The BlocklistKind object
email_domain blocks a whole provider — one entry covers every mailbox at a throwaway domain. device matches the referral's click identifier.
Full schema:
{
"type": "string",
"description": "`email_domain` blocks a whole provider — one entry covers every mailbox at a throwaway domain. `device` matches the referral's click identifier.\n",
"enum": [
"email",
"email_domain",
"device",
"referrer"
]
}The ListResponse object
| Field | Type | Required | Description |
|---|---|---|---|
object | string | Yes | |
has_more | boolean | Yes | |
data | array | Yes |
Full schema:
{
"type": "object",
"required": [
"object",
"data",
"has_more"
],
"properties": {
"object": {
"type": "string",
"const": "list"
},
"has_more": {
"type": "boolean"
},
"data": {
"type": "array",
"items": {}
}
}
}The BlocklistEntry object
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | |
object | string | Yes | |
kind | BlocklistKind | Yes | email_domain blocks a whole provider — one entry covers every mailbox at a throwaway domain. device matches the referral's click identifier. |
value | string | Yes | As entered, shown back verbatim. |
normalized_value | string | No | What matching compares against — lower-cased, with plus-addressing stripped (and dots stripped for Google addresses). This is why Bad+1@Gmail.com and bad@gmail.com are a single entry. |
reason | string or null | No | |
livemode | boolean | Yes | |
created_at | string | Yes |
Full schema:
{
"type": "object",
"required": [
"id",
"object",
"kind",
"value",
"livemode",
"created_at"
],
"properties": {
"id": {
"type": "string",
"example": "bl_123"
},
"object": {
"type": "string",
"const": "blocklist_entry"
},
"kind": {
"$ref": "#/components/schemas/BlocklistKind"
},
"value": {
"type": "string",
"description": "As entered, shown back verbatim."
},
"normalized_value": {
"type": "string",
"description": "What matching compares against — lower-cased, with plus-addressing stripped (and dots stripped for Google addresses). This is why `Bad+1@Gmail.com` and `bad@gmail.com` are a single entry.\n"
},
"reason": {
"type": [
"string",
"null"
],
"maxLength": 500
},
"livemode": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}The Error object
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes |
Full schema:
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"type",
"code",
"message",
"doc_url"
],
"properties": {
"type": {
"type": "string",
"enum": [
"invalid_request_error",
"authentication_error",
"rate_limit_error",
"api_error"
]
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
}
}
}
}
}The BlocklistEntriesCreate object
| Field | Type | Required | Description |
|---|---|---|---|
entries | array | Yes |
Full schema:
{
"type": "object",
"required": [
"entries"
],
"properties": {
"entries": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"type": "object",
"required": [
"kind",
"value"
],
"properties": {
"kind": {
"$ref": "#/components/schemas/BlocklistKind"
},
"value": {
"type": "string",
"maxLength": 320
},
"reason": {
"type": "string",
"maxLength": 500,
"description": "Free text, kept in the account's audit log, which can't be edited or erased. Don't put personal data (names, emails) here.\n"
}
}
}
}
}
}