Skip to content
Frontmail Docs

Send a form (EmailJS-compatible alias)

POST
/api/v1.0/email/send-form
curl --request POST \
  --url https://api.frontmail.dev/api/v1.0/email/send-form \
  --header 'Content-Type: multipart/form-data' \
  --header 'Idempotency-Key: 7f0b6c1e-3a57-4a0e-9d0c-5d3f2d1b2a10' \
  --header 'X-Frontmail-Public-Key: <X-Frontmail-Public-Key>' \
  --form service_id=example \
  --form template_id=example \
  --form user_id=example \
  --form accessToken=example \
  --form cf-turnstile-response=example \
  --form turnstile_token=example \
  --form turnstile_key=org

Multipart/form-data: text fields become template params, file fields become attachments (plan attachment limit).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters”
Idempotency-Key

Unique key per logical send (≤ 255 chars of [A-Za-z0-9_-:.]). Retries with the same key and body return the original response.

string
<= 255 characters
Example
7f0b6c1e-3a57-4a0e-9d0c-5d3f2d1b2a10

Unique key per logical send (≤ 255 chars of [A-Za-z0-9_-:.]). Retries with the same key and body return the original response.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typemultipart/form-data

Reserved fields as listed; every other text field becomes a template param, every file field an attachment.

object
service_id
string
template_id
required
string
user_id
string
accessToken
string
cf-turnstile-response
string
turnstile_token
string
turnstile_key
string
Allowed values: org frontmail
key
additional properties
Any of:
string

Responses

Section titled “ Responses ”

200

Section titled “200”

Accepted. Frontmail clients (X-Frontmail-Client header or Accept: application/json) get the JSON body; EmailJS-style clients get 200 text/plain "OK". Message id and status are always in X-Frontmail-Message-Id / X-Frontmail-Status.

object
message_id
required
string
status
required

held = accepted but waiting for credits; it is sent automatically once credits are added.

string
Allowed values: queued held
status_token
required

Pass as ?token= to GET /v1/messages/{id} with a public key.

string
Example
{
  "message_id": "msg_01j9z3m2c7v8b9n0m1q2w3e4r5",
  "status": "queued"
}

400

Section titled “400”

Invalid request body, query or Idempotency-Key (invalid_body, bad_request, invalid_idempotency_key).

Media typeapplication/json
object
error
required
object
code
required

Stable error code. See https://docs.frontmail.dev/reference/errors/.

string
Allowed values: bad_request invalid_body invalid_idempotency_key unauthorized invalid_public_key invalid_private_key insufficient_credits forbidden origin_not_allowed captcha_required captcha_failed captcha_not_configured headless_blocked recipient_blocked private_key_required private_key_in_browser email_not_verified organization_suspended plan_limit_reached dynamic_recipient_not_allowed dynamic_recipient_requires_captcha dynamic_field_not_allowed link_not_allowed attachments_not_allowed not_found service_not_found template_not_found message_not_found conflict idempotency_conflict payload_too_large attachment_too_large invalid_template_params template_render_failed invalid_recipient service_unavailable_for_template sender_not_configured rate_limited test_send_limit recipient_suppressed internal_error provider_error service_unavailable
message
required
string
docs_url
required
string format: uri
details
Example
{
  "error": {
    "code": "invalid_template_params",
    "message": "Invalid template parameters. email: Enter a valid e-mail address.",
    "docs_url": "https://docs.frontmail.dev/reference/errors/#invalid-template-params",
    "details": {
      "issues": [
        {
          "param": "email",
          "code": "invalid_email",
          "message": "Enter a valid e-mail address."
        }
      ]
    }
  }
}

401

Section titled “401”

Missing or invalid key (unauthorized, invalid_public_key, invalid_private_key).

Media typeapplication/json
object
error
required
object
code
required

Stable error code. See https://docs.frontmail.dev/reference/errors/.

string
Allowed values: bad_request invalid_body invalid_idempotency_key unauthorized invalid_public_key invalid_private_key insufficient_credits forbidden origin_not_allowed captcha_required captcha_failed captcha_not_configured headless_blocked recipient_blocked private_key_required private_key_in_browser email_not_verified organization_suspended plan_limit_reached dynamic_recipient_not_allowed dynamic_recipient_requires_captcha dynamic_field_not_allowed link_not_allowed attachments_not_allowed not_found service_not_found template_not_found message_not_found conflict idempotency_conflict payload_too_large attachment_too_large invalid_template_params template_render_failed invalid_recipient service_unavailable_for_template sender_not_configured rate_limited test_send_limit recipient_suppressed internal_error provider_error service_unavailable
message
required
string
docs_url
required
string format: uri
details
Example
{
  "error": {
    "code": "invalid_template_params",
    "message": "Invalid template parameters. email: Enter a valid e-mail address.",
    "docs_url": "https://docs.frontmail.dev/reference/errors/#invalid-template-params",
    "details": {
      "issues": [
        {
          "param": "email",
          "code": "invalid_email",
          "message": "Enter a valid e-mail address."
        }
      ]
    }
  }
}

402

Section titled “402”

No credits left and the organization uses reject mode (insufficient_credits).

Media typeapplication/json
object
error
required
object
code
required

Stable error code. See https://docs.frontmail.dev/reference/errors/.

string
Allowed values: bad_request invalid_body invalid_idempotency_key unauthorized invalid_public_key invalid_private_key insufficient_credits forbidden origin_not_allowed captcha_required captcha_failed captcha_not_configured headless_blocked recipient_blocked private_key_required private_key_in_browser email_not_verified organization_suspended plan_limit_reached dynamic_recipient_not_allowed dynamic_recipient_requires_captcha dynamic_field_not_allowed link_not_allowed attachments_not_allowed not_found service_not_found template_not_found message_not_found conflict idempotency_conflict payload_too_large attachment_too_large invalid_template_params template_render_failed invalid_recipient service_unavailable_for_template sender_not_configured rate_limited test_send_limit recipient_suppressed internal_error provider_error service_unavailable
message
required
string
docs_url
required
string format: uri
details
Example
{
  "error": {
    "code": "invalid_template_params",
    "message": "Invalid template parameters. email: Enter a valid e-mail address.",
    "docs_url": "https://docs.frontmail.dev/reference/errors/#invalid-template-params",
    "details": {
      "issues": [
        {
          "param": "email",
          "code": "invalid_email",
          "message": "Enter a valid e-mail address."
        }
      ]
    }
  }
}

403

Section titled “403”

Forbidden: origin, CAPTCHA (required, failed, not configured), headless, block list, private key required, suspended, unverified owner e-mail, plan limit, dynamic recipient, attachments.

Media typeapplication/json
object
error
required
object
code
required

Stable error code. See https://docs.frontmail.dev/reference/errors/.

string
Allowed values: bad_request invalid_body invalid_idempotency_key unauthorized invalid_public_key invalid_private_key insufficient_credits forbidden origin_not_allowed captcha_required captcha_failed captcha_not_configured headless_blocked recipient_blocked private_key_required private_key_in_browser email_not_verified organization_suspended plan_limit_reached dynamic_recipient_not_allowed dynamic_recipient_requires_captcha dynamic_field_not_allowed link_not_allowed attachments_not_allowed not_found service_not_found template_not_found message_not_found conflict idempotency_conflict payload_too_large attachment_too_large invalid_template_params template_render_failed invalid_recipient service_unavailable_for_template sender_not_configured rate_limited test_send_limit recipient_suppressed internal_error provider_error service_unavailable
message
required
string
docs_url
required
string format: uri
details
Example
{
  "error": {
    "code": "invalid_template_params",
    "message": "Invalid template parameters. email: Enter a valid e-mail address.",
    "docs_url": "https://docs.frontmail.dev/reference/errors/#invalid-template-params",
    "details": {
      "issues": [
        {
          "param": "email",
          "code": "invalid_email",
          "message": "Enter a valid e-mail address."
        }
      ]
    }
  }
}

404

Section titled “404”

Template, service or message not found.

Media typeapplication/json
object
error
required
object
code
required

Stable error code. See https://docs.frontmail.dev/reference/errors/.

string
Allowed values: bad_request invalid_body invalid_idempotency_key unauthorized invalid_public_key invalid_private_key insufficient_credits forbidden origin_not_allowed captcha_required captcha_failed captcha_not_configured headless_blocked recipient_blocked private_key_required private_key_in_browser email_not_verified organization_suspended plan_limit_reached dynamic_recipient_not_allowed dynamic_recipient_requires_captcha dynamic_field_not_allowed link_not_allowed attachments_not_allowed not_found service_not_found template_not_found message_not_found conflict idempotency_conflict payload_too_large attachment_too_large invalid_template_params template_render_failed invalid_recipient service_unavailable_for_template sender_not_configured rate_limited test_send_limit recipient_suppressed internal_error provider_error service_unavailable
message
required
string
docs_url
required
string format: uri
details
Example
{
  "error": {
    "code": "invalid_template_params",
    "message": "Invalid template parameters. email: Enter a valid e-mail address.",
    "docs_url": "https://docs.frontmail.dev/reference/errors/#invalid-template-params",
    "details": {
      "issues": [
        {
          "param": "email",
          "code": "invalid_email",
          "message": "Enter a valid e-mail address."
        }
      ]
    }
  }
}

409

Section titled “409”

Idempotency-Key reused with a different body, or still in progress (idempotency_conflict).

Media typeapplication/json
object
error
required
object
code
required

Stable error code. See https://docs.frontmail.dev/reference/errors/.

string
Allowed values: bad_request invalid_body invalid_idempotency_key unauthorized invalid_public_key invalid_private_key insufficient_credits forbidden origin_not_allowed captcha_required captcha_failed captcha_not_configured headless_blocked recipient_blocked private_key_required private_key_in_browser email_not_verified organization_suspended plan_limit_reached dynamic_recipient_not_allowed dynamic_recipient_requires_captcha dynamic_field_not_allowed link_not_allowed attachments_not_allowed not_found service_not_found template_not_found message_not_found conflict idempotency_conflict payload_too_large attachment_too_large invalid_template_params template_render_failed invalid_recipient service_unavailable_for_template sender_not_configured rate_limited test_send_limit recipient_suppressed internal_error provider_error service_unavailable
message
required
string
docs_url
required
string format: uri
details
Example
{
  "error": {
    "code": "invalid_template_params",
    "message": "Invalid template parameters. email: Enter a valid e-mail address.",
    "docs_url": "https://docs.frontmail.dev/reference/errors/#invalid-template-params",
    "details": {
      "issues": [
        {
          "param": "email",
          "code": "invalid_email",
          "message": "Enter a valid e-mail address."
        }
      ]
    }
  }
}

413

Section titled “413”

Request or attachments too large (payload_too_large, attachment_too_large).

Media typeapplication/json
object
error
required
object
code
required

Stable error code. See https://docs.frontmail.dev/reference/errors/.

string
Allowed values: bad_request invalid_body invalid_idempotency_key unauthorized invalid_public_key invalid_private_key insufficient_credits forbidden origin_not_allowed captcha_required captcha_failed captcha_not_configured headless_blocked recipient_blocked private_key_required private_key_in_browser email_not_verified organization_suspended plan_limit_reached dynamic_recipient_not_allowed dynamic_recipient_requires_captcha dynamic_field_not_allowed link_not_allowed attachments_not_allowed not_found service_not_found template_not_found message_not_found conflict idempotency_conflict payload_too_large attachment_too_large invalid_template_params template_render_failed invalid_recipient service_unavailable_for_template sender_not_configured rate_limited test_send_limit recipient_suppressed internal_error provider_error service_unavailable
message
required
string
docs_url
required
string format: uri
details
Example
{
  "error": {
    "code": "invalid_template_params",
    "message": "Invalid template parameters. email: Enter a valid e-mail address.",
    "docs_url": "https://docs.frontmail.dev/reference/errors/#invalid-template-params",
    "details": {
      "issues": [
        {
          "param": "email",
          "code": "invalid_email",
          "message": "Enter a valid e-mail address."
        }
      ]
    }
  }
}

422

Section titled “422”

Invalid template params, recipient or rendering error.

Media typeapplication/json
object
error
required
object
code
required

Stable error code. See https://docs.frontmail.dev/reference/errors/.

string
Allowed values: bad_request invalid_body invalid_idempotency_key unauthorized invalid_public_key invalid_private_key insufficient_credits forbidden origin_not_allowed captcha_required captcha_failed captcha_not_configured headless_blocked recipient_blocked private_key_required private_key_in_browser email_not_verified organization_suspended plan_limit_reached dynamic_recipient_not_allowed dynamic_recipient_requires_captcha dynamic_field_not_allowed link_not_allowed attachments_not_allowed not_found service_not_found template_not_found message_not_found conflict idempotency_conflict payload_too_large attachment_too_large invalid_template_params template_render_failed invalid_recipient service_unavailable_for_template sender_not_configured rate_limited test_send_limit recipient_suppressed internal_error provider_error service_unavailable
message
required
string
docs_url
required
string format: uri
details
Example
{
  "error": {
    "code": "invalid_template_params",
    "message": "Invalid template parameters. email: Enter a valid e-mail address.",
    "docs_url": "https://docs.frontmail.dev/reference/errors/#invalid-template-params",
    "details": {
      "issues": [
        {
          "param": "email",
          "code": "invalid_email",
          "message": "Enter a valid e-mail address."
        }
      ]
    }
  }
}

429

Section titled “429”

Rate limited – see Retry-After (seconds).

Media typeapplication/json
object
error
required
object
code
required

Stable error code. See https://docs.frontmail.dev/reference/errors/.

string
Allowed values: bad_request invalid_body invalid_idempotency_key unauthorized invalid_public_key invalid_private_key insufficient_credits forbidden origin_not_allowed captcha_required captcha_failed captcha_not_configured headless_blocked recipient_blocked private_key_required private_key_in_browser email_not_verified organization_suspended plan_limit_reached dynamic_recipient_not_allowed dynamic_recipient_requires_captcha dynamic_field_not_allowed link_not_allowed attachments_not_allowed not_found service_not_found template_not_found message_not_found conflict idempotency_conflict payload_too_large attachment_too_large invalid_template_params template_render_failed invalid_recipient service_unavailable_for_template sender_not_configured rate_limited test_send_limit recipient_suppressed internal_error provider_error service_unavailable
message
required
string
docs_url
required
string format: uri
details
Example
{
  "error": {
    "code": "invalid_template_params",
    "message": "Invalid template parameters. email: Enter a valid e-mail address.",
    "docs_url": "https://docs.frontmail.dev/reference/errors/#invalid-template-params",
    "details": {
      "issues": [
        {
          "param": "email",
          "code": "invalid_email",
          "message": "Enter a valid e-mail address."
        }
      ]
    }
  }
}

Headers

Section titled “Headers”
Retry-After
required

Seconds to wait before retrying.

string

Seconds to wait before retrying.

451

Section titled “451”

A recipient is on the suppression list (recipient_suppressed).

Media typeapplication/json
object
error
required
object
code
required

Stable error code. See https://docs.frontmail.dev/reference/errors/.

string
Allowed values: bad_request invalid_body invalid_idempotency_key unauthorized invalid_public_key invalid_private_key insufficient_credits forbidden origin_not_allowed captcha_required captcha_failed captcha_not_configured headless_blocked recipient_blocked private_key_required private_key_in_browser email_not_verified organization_suspended plan_limit_reached dynamic_recipient_not_allowed dynamic_recipient_requires_captcha dynamic_field_not_allowed link_not_allowed attachments_not_allowed not_found service_not_found template_not_found message_not_found conflict idempotency_conflict payload_too_large attachment_too_large invalid_template_params template_render_failed invalid_recipient service_unavailable_for_template sender_not_configured rate_limited test_send_limit recipient_suppressed internal_error provider_error service_unavailable
message
required
string
docs_url
required
string format: uri
details
Example
{
  "error": {
    "code": "invalid_template_params",
    "message": "Invalid template parameters. email: Enter a valid e-mail address.",
    "docs_url": "https://docs.frontmail.dev/reference/errors/#invalid-template-params",
    "details": {
      "issues": [
        {
          "param": "email",
          "code": "invalid_email",
          "message": "Enter a valid e-mail address."
        }
      ]
    }
  }
}

500

Section titled “500”

Unexpected error; details.request_id identifies the request.

Media typeapplication/json
object
error
required
object
code
required

Stable error code. See https://docs.frontmail.dev/reference/errors/.

string
Allowed values: bad_request invalid_body invalid_idempotency_key unauthorized invalid_public_key invalid_private_key insufficient_credits forbidden origin_not_allowed captcha_required captcha_failed captcha_not_configured headless_blocked recipient_blocked private_key_required private_key_in_browser email_not_verified organization_suspended plan_limit_reached dynamic_recipient_not_allowed dynamic_recipient_requires_captcha dynamic_field_not_allowed link_not_allowed attachments_not_allowed not_found service_not_found template_not_found message_not_found conflict idempotency_conflict payload_too_large attachment_too_large invalid_template_params template_render_failed invalid_recipient service_unavailable_for_template sender_not_configured rate_limited test_send_limit recipient_suppressed internal_error provider_error service_unavailable
message
required
string
docs_url
required
string format: uri
details
Example
{
  "error": {
    "code": "invalid_template_params",
    "message": "Invalid template parameters. email: Enter a valid e-mail address.",
    "docs_url": "https://docs.frontmail.dev/reference/errors/#invalid-template-params",
    "details": {
      "issues": [
        {
          "param": "email",
          "code": "invalid_email",
          "message": "Enter a valid e-mail address."
        }
      ]
    }
  }
}