Skip to content
Frontmail Docs

Send up to 100 emails

POST
/v1/send-batch
curl --request POST \
  --url https://api.frontmail.dev/v1/send-batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 7f0b6c1e-3a57-4a0e-9d0c-5d3f2d1b2a10' \
  --data '{ "messages": [ { "service_id": "example", "template_id": "example", "template_params": { "name": "Jan", "email": "jan@example.com", "message": "Hello!" }, "idempotency_key": "example", "attachments": [ { "filename": "example", "content_type": "example", "content_base64": "example" } ] } ] }'

Private key only. Max 100 messages; each item is processed independently (own idempotency key, own result). With an Idempotency-Key header and no item key, items use <header>:<index>.

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 typeapplication/json
object
messages
required
Array<object>
>= 1 items <= 100 items
object
service_id
string
<= 64 characters
template_id
required
string
>= 1 characters <= 64 characters
template_params

Values for the template’s parameters (validated against its schema).

object
key
additional properties
Example
{
  "name": "Jan",
  "email": "jan@example.com",
  "message": "Hello!"
}
idempotency_key
string
<= 255 characters
attachments
Array
<= 20 items
Any of:
object
filename
required
string
>= 1 characters <= 255 characters
content_type
string
<= 255 characters
content_base64
required
string
>= 1 characters

Responses

Section titled “ Responses ”

200

Section titled “200”

Per-item results.

Media typeapplication/json
object
results
required
Array
Any of:
object
index
required
integer
message_id
required
string
status
required
string
Allowed values: queued held
status_token
required
string
Example
{
  "results": [
    {
      "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."
        }
      ]
    }
  }
}

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."
        }
      ]
    }
  }
}

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."
        }
      ]
    }
  }
}

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.

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."
        }
      ]
    }
  }
}