# 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 %}