# v0 - API Reference

## Get Burners

<mark style="color:blue;">`GET`</mark> `https://burnermail.io/api/burner_emails`

This endpoint allows you to get a list of your burners.

#### Headers

| Name     | Type   | Description         |
| -------- | ------ | ------------------- |
| API\_KEY | string | Authentication key. |

{% tabs %}
{% tab title="200 Burner list successfully retrieved." %}

```
[
    {
        "email": "abc123@tryburner.email",
        "active": true,
        "forwarded_emails": 19,
        "blocked_emails": 0,
        "description": ""
    },
    {
        "email": "cba321@tryburner.email",
        "active": true,
        "forwarded_emails": 91,
        "blocked_emails": 0,
        "description": ""
    }, 
    ...
]
```

{% endtab %}

{% tab title="401 Invalid (empty, incorrect or missing) API\_KEY header." %}

```
Empty response.
```

{% endtab %}
{% endtabs %}

## Generate Burner

<mark style="color:green;">`POST`</mark> `https://burnermail.io/api/burner_emails`

This endpoint generates a random burner with the specified domain name or the default one that you have set in Settings.

#### Headers

| Name     | Type   | Description         |
| -------- | ------ | ------------------- |
| API\_KEY | string | Authentication key. |

#### Request Body

| Name   | Type   | Description                                                                                         |
| ------ | ------ | --------------------------------------------------------------------------------------------------- |
| domain | string | Optionally provide a domain name. If no domain name is provided, then the default one will be used. |

{% tabs %}
{% tab title="201 The burner email address was successfully created and can now be used." %}

```
{
    "email": "wilson.746kj2@tryburner.email",
    "active": true,
    "forwarded_emails": 0,
    "blocked_emails": 0,
    "description": ""
}
```

{% endtab %}

{% tab title="401 Invalid (empty, incorrect or missing) API\_KEY header." %}

```
Empty response.
```

{% endtab %}

{% tab title="422 Invalid domain specified." %}

```
{
    "error": "Invalid domain"
}
```

{% endtab %}
{% endtabs %}

## Generate Custom Burner

<mark style="color:green;">`POST`</mark> `https://burnermail.io/api/burner_emails/custom`

This endpoint generates a custom burner email address.

#### Headers

| Name     | Type   | Description         |
| -------- | ------ | ------------------- |
| API\_KEY | string | Authentication key. |

#### Request Body

| Name    | Type   | Description                                                                                          |
| ------- | ------ | ---------------------------------------------------------------------------------------------------- |
| address | string | The burner email address prefix - the part before the "at" sign (**address**@tryburner.email)        |
| domain  | string | The domain for the burner email address - the part after the "at" sign (address@**tryburner.email)** |

{% tabs %}
{% tab title="201 Successfully created custom burner." %}

```
{
    "email": "abc123@tryburner.email",
    "active": true,
    "forwarded_emails": 0,
    "blocked_emails": 0,
    "description": ""
}
```

{% endtab %}

{% tab title="422 Invalid domain specified." %}

```
{
    "error": "Invalid domain"
}
```

{% endtab %}
{% endtabs %}

## Delete Burner

<mark style="color:green;">`POST`</mark> `https://burnermail.io/api/burner_emails/delete`

This endpoint deletes a specific burner.\
**Please keep in mind that his action is PERMANENT and there is no going back!**

#### Headers

| Name     | Type   | Description         |
| -------- | ------ | ------------------- |
| API\_KEY | string | Authentication key. |

#### Request Body

| Name          | Type   | Description                                                                                |
| ------------- | ------ | ------------------------------------------------------------------------------------------ |
| burner\_email | string | The full burner email address that you want to delete. (*eg. <burner123@tryburner.email>*) |

{% tabs %}
{% tab title="201 The burner email address was successfully deleted." %}

```
{
    "success": true
}
```

{% endtab %}

{% tab title="401 Invalid (empty, incorrect or missing) API\_KEY header." %}

```
Empty response.
```

{% endtab %}

{% tab title="422 Invalid email address specified." %}

```
{
    "error": "Invalid burner email address"
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.burnermail.io/master.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.