> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avraapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Check a disposable email address
> Check one email address for disposable or temporary-email signals.
Use this endpoint when your application needs a disposable-email signal during sign-up, account recovery, or abuse-prevention checks. It evaluates one email address and returns whether its domain appears in the configured disposable-email lists.
**Live Testing Guide:** Before using **Try it**, create a Development project, then enter its **Client ID** and **Client Secret**. Configure the relevant provider for that project before sending the request.
## API endpoint
```text title="POST" theme={null}
https://avraapi.com/api/v1/security/burner-email-shield
```
## Request fields
| Field | Required | Rules |
| - | - | - |
| `email` | Yes | A string containing an RFC-compatible email address, up to 255 characters. |
Outside the documentation Playground, keep the Project Client Secret on your backend. The request body intentionally uses `POST` so an email address is not placed in the URL. Only submit addresses that you are permitted to process.
## Result fields
| Field | Type | Notes |
| - | - | - |
| `email` | string | The email address evaluated by the service. |
| `domain` | string | The extracted, normalised domain. |
| `is_valid_syntax` | boolean | Whether the address passed the service's syntax validation. |
| `is_disposable` | boolean | Whether the domain, or a parent domain, was found in a disposable-email list. |
| `source` | string | Match source: `custom`, `global`, or `none`. |
| `execution_time_ms` | number | Time spent evaluating the request, in milliseconds. |
`is_disposable: false` means the configured lists did not contain a matching domain. It is not a guarantee that an address is owned by a real person or safe to trust.
## Request example
```bash curl theme={null} theme={null}
curl --request POST "https://avraapi.com/api/v1/security/burner-email-shield" \
--header "X-API-KEY: YOUR_PROJECT_CLIENT_ID" \
--header "X-API-SECRET: YOUR_PROJECT_CLIENT_SECRET" \
--header "X-ENV: development" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{"email":"documentation@example.invalid"}'
```
## Response example
```json theme={null}
{
"success": true,
"request_id": "82512122-5a64-459c-a0cb-0ba07be4a600",
"data": {
"email": "hodil14324@ellbit.com",
"domain": "ellbit.com",
"is_valid_syntax": true,
"is_disposable": true,
"source": "custom",
"execution_time_ms": 5.89
}
}
```
## Error codes
| HTTP | `error.code` | When it happens | What to do |
| - | - | - | - |
| `401` | unauthorized | Credentials are missing, invalid, inactive, or do not match the selected environment. | Check your backend secret configuration and `X-ENV`. |
| `402` | insufficient\_funds | The selected Security integration requires credits that are unavailable. | Check the project's current service configuration and balance. |
| `422` | validation\_failed | `email` is missing, is not a string, is not a valid email address, or exceeds 255 characters. The response includes field details. | Correct the request field and submit a new request. |
| `422` | provider\_selection\_failed | The required Security provider is unavailable for the project environment. | Enable or configure the provider for the selected environment. |
| `429` | rate\_limit\_exceeded | The configured request limit was reached. | Respect `Retry-After` when present; do not retry in a tight loop. |
| `500` | internal\_error | The disposable-email check could not complete. | Retry only if your workflow permits it, retaining the request ID. |
| `503` | project\_paused | The project is paused. | Reactivate the project before retrying. |
Keep the JSON `request_id` or `X-APIX-Request-ID` response header with your support record. It is the safest way for AvraAPI support to trace a request.
See the [REST API guide](/api-reference/rest-api) for shared credential, privacy, and error-handling guidance.
## Playground resources
The generated reference below lists this endpoint's API standard details: request fields, authorizations, and response schema. The complete integration guide, request and response examples, and endpoint-specific error handling are above.
## OpenAPI
````yaml api-reference/provider-api.openapi.yaml POST /security/burner-email-shield
openapi: 3.0.3
info:
title: AvraAPI Provider API
version: 1.0.0
description: >-
The reviewed public contract for AvraAPI provider services. Operations are
added to this document only after their route, validation, response,
privacy, usage, and public-safety contracts have been verified.
servers:
- url: https://avraapi.com/api/v1
description: AvraAPI REST API v1
security:
- ApiKeyHeader: []
ApiSecretHeader: []
tags:
- name: Currency
description: Currency codes, exchange rates, and conversion.
- name: SMS
description: Messaging operations through configured AvraAPI providers.
- name: Security
description: IP and email security checks.
- name: Location
description: IP geolocation and intelligence.
- name: Utilities
description: QR code, barcode, and PDF generation.
paths:
/security/burner-email-shield:
post:
tags:
- Security
summary: Check a disposable email address
description: >-
Checks one email address for disposable or temporary-email signals. The
endpoint accepts the address in a POST body so it is not placed in the
URL. Process only addresses that you are permitted to use.
operationId: checkBurnerEmailShield
parameters:
- $ref: '#/components/parameters/XEnvironmentHeader'
- $ref: '#/components/parameters/AcceptJsonHeader'
- $ref: '#/components/parameters/XPrivacyModeHeader'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BurnerEmailShieldRequest'
examples:
disposable_email:
summary: Documentation-only reserved email address
value:
email: documentation@example.invalid
responses:
'200':
description: Disposable-email result.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/BurnerEmailShieldResponse'
examples:
matched_email:
summary: Domain found in the configured list
value:
success: true
request_id: 82512122-5a64-459c-a0cb-0ba07be4a600
data:
email: hodil14324@ellbit.com
domain: ellbit.com
is_valid_syntax: true
is_disposable: true
source: custom
execution_time_ms: 5.89
'401':
description: >-
Missing, invalid, inactive, or environment-mismatched project
credentials.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/SecurityUnauthorizedErrorEnvelope'
examples:
unauthorized:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: unauthorized
message:
details: {}
meta: {}
'402':
description: >-
The selected Security integration requires credits that are
unavailable.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/SecurityInsufficientFundsErrorEnvelope'
examples:
insufficient_funds:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: insufficient_funds
message:
details: {}
meta: {}
'422':
description: >-
Invalid request fields. See the Error codes table for the separate
provider-selection outcome.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/SecurityValidationErrorEnvelope'
examples:
validation_failed:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: validation_failed
message:
details: {}
meta: {}
'429':
description: The configured Security request limit has been reached.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
Retry-After:
$ref: '#/components/headers/RetryAfterHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/SecurityRateLimitedErrorEnvelope'
examples:
rate_limit_exceeded:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: rate_limit_exceeded
message:
details: {}
meta: {}
'500':
description: The disposable-email check could not complete.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/SecurityInternalErrorEnvelope'
examples:
internal_error:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: internal_error
message:
details: {}
meta: {}
'503':
description: The project is paused and cannot make API requests.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/SecurityProjectPausedErrorEnvelope'
examples:
project_paused:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: project_paused
message:
details: {}
meta: {}
components:
parameters:
XEnvironmentHeader:
name: X-ENV
in: header
required: false
description: >-
Selects the Development credential environment. The Documentation
Playground exposes Development values only; normal backend integrations
may use their documented Production credentials outside this tool.
schema:
type: string
enum:
- dev
- development
default: development
AcceptJsonHeader:
name: Accept
in: header
required: false
description: Requests a JSON response where the selected operation supports JSON.
schema:
type: string
example: application/json
XPrivacyModeHeader:
name: X-Privacy-Mode
in: header
required: false
description: >-
Optional privacy override. Turn this on to request that AvraAPI suppress
request-payload storage in observability logs for this request.
schema:
type: boolean
default: false
example: true
schemas:
BurnerEmailShieldRequest:
type: object
required:
- email
properties:
email:
type: string
format: email
maxLength: 255
description: An RFC-compatible email address.
example: documentation@example.invalid
BurnerEmailShieldResponse:
allOf:
- $ref: '#/components/schemas/ApiSuccessEnvelope'
- type: object
properties:
data:
$ref: '#/components/schemas/BurnerEmailShieldData'
SecurityUnauthorizedErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- unauthorized
example: unauthorized
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
SecurityInsufficientFundsErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- insufficient_funds
example: insufficient_funds
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
SecurityValidationErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- validation_failed
example: validation_failed
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
SecurityRateLimitedErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- rate_limit_exceeded
example: rate_limit_exceeded
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
SecurityInternalErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- internal_error
example: internal_error
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
SecurityProjectPausedErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- project_paused
example: project_paused
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
ApiSuccessEnvelope:
type: object
required:
- success
- request_id
- data
properties:
success:
type: boolean
enum:
- true
request_id:
type: string
format: uuid
description: Include this value when contacting AvraAPI support.
data:
description: Operation-specific result data.
nullable: true
BurnerEmailShieldData:
type: object
required:
- email
- domain
- is_valid_syntax
- is_disposable
- source
- execution_time_ms
properties:
email:
type: string
format: email
description: The email address evaluated by the service.
domain:
type: string
description: The extracted, normalised domain.
is_valid_syntax:
type: boolean
description: Whether the address passed syntax validation.
is_disposable:
type: boolean
description: Whether the domain or a parent domain is in a disposable-email list.
source:
type: string
enum:
- custom
- global
- none
description: The matching disposable-email list, or none when there was no match.
execution_time_ms:
type: number
format: float
description: Time spent evaluating the request, in milliseconds.
headers:
RequestIdHeader:
description: AvraAPI request identifier for support and troubleshooting.
schema:
type: string
format: uuid
RetryAfterHeader:
description: Seconds to wait before retrying a rate-limited request.
schema:
type: integer
minimum: 0
securitySchemes:
ApiKeyHeader:
type: apiKey
in: header
name: X-API-KEY
description: >-
Your Development project's Client ID. Enter your own value in the
Documentation Playground.
ApiSecretHeader:
type: apiKey
in: header
name: X-API-SECRET
description: >-
Your Development project's Client Secret. Mintlify does not proxy these
requests; the browser sends them directly to AvraAPI. Never enter a
Production secret in the Documentation Playground.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.