> For the complete documentation index, see [llms.txt](https://docs.smtpd.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.smtpd.dev/api/email-templates-in-beta-1.md).

# Forms

These API endpoints support the abaility to add forms for data collection. Each form is attched to a Sending Profile link domain.

## Create new email form

<mark style="color:green;">`POST`</mark> `https://api.smtpd.dev/api/v1/email/form`

This endpoint creates a new email form endpoint.

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

#### Request Body

| Name                                                           | Type    | Description                                    |
| -------------------------------------------------------------- | ------- | ---------------------------------------------- |
| tags                                                           | object  |                                                |
| default\_redirect<mark style="color:red;">\*</mark>            | boolean |                                                |
| success\_redirect<mark style="color:red;">\*</mark>            | boolean |                                                |
| failure\_redirect<mark style="color:red;">\*</mark>            | string  |                                                |
| required\_fields<mark style="color:red;">\*</mark>             | string  |                                                |
| notification\_email\_address<mark style="color:red;">\*</mark> | string  |                                                |
| form\_name<mark style="color:red;">\*</mark>                   | string  | Form name                                      |
| link\_domain<mark style="color:red;">\*</mark>                 | string  | The link domain from an active sending profile |
| enable\_email\_notification                                    | bool    | Enable Notification                            |

{% tabs %}
{% tab title="200: OK Form created" %}

```
{
	"form_id": "9dda916c-086e-40a6-a9d9-2dbe8af76c38",
	"form_key": "2NzhS8VWj1ODBqA3vmwSb4HnbPN",
	"form_name": "Contact Form - NZ",
	"sending_profile_id": "f73d640e-d372-11ed-bdc4-664cfc1c0a60",
	"notification_email_address": "jimmy@yoursendingdomain.com",
	"enable_email_notification": true,
	"notification_email_address_verified": false,
	"form_endpoint": "https://yoursendingdomain.com/f/2NzhS8VWj1ODBqA3vmwSb4HnbPN",
	"default_redirect": "https://www.yoursendingdomain.com",
	"success_redirect": "https://www.yoursendingdomain.com/thank-you",
	"failure_redirect": "https://www.yoursendingdomain.com/contactus/error",
	"required_fields": [
		"email",
		"name"
	],
	"tags": [
		"local"
	],
	"state": "creating",
	"created_at_utc": 1680672814,
	"modified_at_utc": 1680672814
}
```

{% endtab %}
{% endtabs %}

## Get Email Form

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/email/form/:id`

This endpoint allows you to get the form setup details by ID

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

{% tabs %}
{% tab title="404 " %}

```
{
  "code": 40401,
  "message": "Resource ID provided is invalid"
}
```

{% endtab %}

{% tab title="200: OK " %}

```
{
	"form_id": "7f4be122-5708-4353-afd2-b5a0b6030b16",
	"form_key": "2Nzh9ps32LyFYAkwOO4zh73giSP",
	"form_name": "Contact Us - NZ",
	"sending_profile_id": "f73d640e-d372-11ed-bdc4-664cfc1c0a60",
	"notification_email_address": "jimmy@yoursendingdomain.com",
	"enable_email_notification": true,
	"notification_email_address_verified": false,
	"form_endpoint": "https://yoursendingdomain.com/f/2Nzh9ps32LyFYAkwOO4zh73giSP",
	"default_redirect": "https://www.yoursendingdomain.com",
	"success_redirect": "https://www.yoursendingdomain.com/thank-you",
	"failure_redirect": "https://www.yoursendingdomain.com/contactus/error",
	"required_fields": [
		"email",
		"name"
	],
	"tags": [
		"local"
	],
	"submission_count": 910,
	"state": "disabled",
	"created_at_utc": 1680672669,
	"modified_at_utc": 1680675564
}
```

{% endtab %}
{% endtabs %}

## Disable Email form

<mark style="color:orange;">`PUT`</mark> `https://api.smtpd.dev/api/v1/email/form/:id/disable`

This endpoint disables a form. After a form has been disabled it may take upto 60mins before the endpoint is disabled.

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

{% tabs %}
{% tab title="200 Form disabled" %}

```
null
```

{% endtab %}

{% tab title="404 " %}

```
{
  "code": 40401,
  "message": "Resource ID provided is invalid"
}
```

{% endtab %}
{% endtabs %}