Private API Examples

These examples use the production base URL:

https://html.contact

Use a private API key that starts with hc_live_. Keep private keys on trusted servers, jobs, scripts, and approved agents only.

For browser forms that use public hc_pub_ keys, see HTML Forms and Examples.

Set example values

Set these variables before running the examples. Replace every value ending in _REPLACE with a real value from your account.

export HC_API_KEY="hc_live_REPLACE"
export FORM_ID="form_REPLACE"
export SUBMISSION_ID="sub_REPLACE"
export ATTACHMENT_ID="att_REPLACE"

Variable	Replace with
HC_API_KEY	A private API key from your account
FORM_ID	A form ID returned by the Forms API
SUBMISSION_ID	A submission ID returned by a submission list or detail response
ATTACHMENT_ID	An attachment ID from the submission detail response

List forms

Requires a Read only or Form manager key.

curl "https://html.contact/api/v1/forms" \
  -H "Authorization: Bearer $HC_API_KEY"

Response shape:

{
  "ok": true,
  "forms": []
}

Each form includes its ID, public key, name, status, allowed domains, recipient settings, and generated HTML snippet.

Create a form

Requires a Form manager key.

curl "https://html.contact/api/v1/forms" \
  -H "Authorization: Bearer $HC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website contact",
    "recipientEmail": "owner@example.com",
    "ccEmail": "ops@example.com",
    "bccEmail": null,
    "allowedDomain": "example.com",
    "defaultSubject": "New website inquiry",
    "defaultIntro": "A new message arrived from your website.",
    "defaultRedirectUrl": "https://example.com/thanks"
  }'

recipientEmail, ccEmail, and bccEmail must already be verified recipient settings on the account.

Update a form

Requires a Form manager key.

curl -X PATCH "https://html.contact/api/v1/forms/$FORM_ID" \
  -H "Authorization: Bearer $HC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main contact form",
    "allowedDomains": ["example.com", "www.example.com"],
    "allowDirectPosts": false,
    "status": "active"
  }'

allowDirectPosts: true accepts trusted server or curl posts without browser source headers. Leave it off for normal website forms.

Duplicate a form

Requires a Form manager key.

curl -X POST "https://html.contact/api/v1/forms/$FORM_ID/duplicate" \
  -H "Authorization: Bearer $HC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website contact backup"
  }'

Duplicating copies recipients, allowed domains, defaults, and generated snippet behavior from the source form.

Send a test email

Requires a Form manager key.

curl -X POST "https://html.contact/api/v1/forms/$FORM_ID/test-email" \
  -H "Authorization: Bearer $HC_API_KEY"

Test emails send to the verified primary recipient and any verified, healthy CC/BCC recipients.

Send recipient verification

Requires a Form manager key.

curl -X POST "https://html.contact/api/v1/forms/$FORM_ID/verify-recipient" \
  -H "Authorization: Bearer $HC_API_KEY"

If the action is rate-limited, the response includes retry_after_seconds.

List submissions

Requires a Read only or Form manager key.

curl "https://html.contact/api/v1/forms/$FORM_ID/submissions?folder=inbox&limit=50" \
  -H "Authorization: Bearer $HC_API_KEY"

Workspace-wide submissions:

curl "https://html.contact/api/v1/forms/all/submissions?folder=spam&q=casino" \
  -H "Authorization: Bearer $HC_API_KEY"

Response shape:

{
  "ok": true,
  "submissions": [],
  "next_cursor": null,
  "counts": {
    "inbox": 0,
    "spam": 0
  }
}

Use next_cursor as the cursor query parameter to load the next page.

Export CSV

Requires a Read only or Form manager key.

curl -L "https://html.contact/api/v1/forms/all/submissions.csv?folder=inbox&limit=5000" \
  -H "Authorization: Bearer $HC_API_KEY" \
  -o submissions.csv

CSV exports include attachment count, filenames, sizes, and authenticated download links when attachments exist.

Get submission detail

Requires a Read only or Form manager key.

curl "https://html.contact/api/v1/submissions/$SUBMISSION_ID" \
  -H "Authorization: Bearer $HC_API_KEY"

Detail responses include submitted field data, source metadata, email status, events, and attachment metadata.

Download an attachment

Requires a Read only or Form manager key.

curl -L "https://html.contact/api/v1/submissions/$SUBMISSION_ID/attachments/$ATTACHMENT_ID" \
  -H "Authorization: Bearer $HC_API_KEY" \
  -o attachment.bin

For safe previewable file types, request inline preview:

curl -L "https://html.contact/api/v1/submissions/$SUBMISSION_ID/attachments/$ATTACHMENT_ID?disposition=inline" \
  -H "Authorization: Bearer $HC_API_KEY"

Attachment metadata is kept separately from the file content, and files are downloaded through authenticated attachment endpoints.

Get usage summary

Requires a Read only or Form manager key.

curl "https://html.contact/api/v1/usage" \
  -H "Authorization: Bearer $HC_API_KEY"

Response shape:

{
  "ok": true,
  "usage": {
    "forms_count": 3,
    "submissions_count": 187,
    "used": 187,
    "limit": 1000,
    "plan": "starter",
    "plan_label": "Starter",
    "period_end": "2026-07-17T00:00:00.000Z",
    "is_over_limit": false
  }
}

OpenAPI

Open raw OpenAPI JSON
View in Swagger UI