Skip to main content
POST
/
emails
cURL
curl -X POST https://api.arkhq.io/v1/emails \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "YOUR_TENANT_ID",
    "from": "hello@yourdomain.com",
    "to": ["user@example.com"],
    "subject": "Hello World",
    "html": "<h1>Welcome!</h1>"
  }'
{
  "success": true,
  "data": {
    "id": "aBc123XyZ456",
    "tenantId": "cm6abc123def456",
    "messageId": "<abc123@mail.arkhq.io>",
    "to": [
      "user@example.com"
    ],
    "status": "pending"
  },
  "meta": {
    "requestId": "req_xyz789"
  }
}

Authorizations

​
Authorization
string
header
required

Use your API key from arkhq.io/org/credentials

Authorization: Bearer YOUR_API_KEY

Headers

​
Idempotency-Key
string

Unique key for idempotent requests. If a request with this key was already processed, the cached response is returned. Keys expire after 24 hours.

Maximum string length: 255
Pattern: ^[\w\-_.~]+$

Body

application/json

Email message to send.

Size limits:

  • Total message size (including attachments): 14MB maximum
  • HTML body: 5MB maximum
  • Plain text body: 5MB maximum
  • Individual attachment: 10MB maximum
​
from
string
required

Sender email address. Must be from a verified domain OR use sandbox mode.

Supported formats:

  • Email only: hello@yourdomain.com
  • With display name: Acme <hello@yourdomain.com>
  • With quoted name: "Acme Support" <support@yourdomain.com>

The domain portion must match a verified sending domain in your account.

Sandbox mode: Use sandbox@arkhq.io to send test emails without domain verification. Sandbox emails can only be sent to organization members and are limited to 10 per day.

Minimum string length: 1
Example:

"Acme <hello@acme.com>"

​
to
string<email>[]
required

Recipient email addresses (max 50)

Required array length: 1 - 50 elements
Example:
["user@example.com"]
​
subject
string
required

Email subject line

Required string length: 1 - 998
​
tenantId
string | null

The tenant ID to send this email from. Determines which tenant's configuration (domains, webhooks, tracking) is used.

  • If your API key is scoped to a specific tenant, this must match that tenant or be omitted.
  • If your API key is org-level, specify the tenant to send from.
  • If omitted, the organization's default tenant is used.
Example:

"cm6abc123def456"

​
cc
string<email>[] | null

CC recipients (accepts null)

Maximum array length: 50
​
bcc
string<email>[] | null

BCC recipients (accepts null)

Maximum array length: 50
​
replyTo
string<email> | null

Reply-to address (accepts null)

​
html
string | null

HTML body content (accepts null). Maximum 5MB (5,242,880 characters). Combined with attachments, the total message must not exceed 14MB.

Maximum string length: 5242880
​
text
string | null

Plain text body (accepts null, auto-generated from HTML if not provided). Maximum 5MB (5,242,880 characters).

Maximum string length: 5242880
​
tag
string | null

Tag for categorization and filtering (accepts null)

Maximum string length: 1000
​
headers
object

Custom email headers (accepts null)

​
attachments
object[] | null

File attachments (accepts null)

​
metadata
object

Custom key-value pairs attached to an email for webhook correlation.

When you send an email with metadata, these key-value pairs are:

  • Stored with the message
  • Returned in all webhook event payloads (MessageSent, MessageBounced, etc.)
  • Never visible to email recipients

This is useful for correlating webhook events with your internal systems (e.g., user IDs, order IDs, campaign identifiers).

Validation Rules:

  • Maximum 10 keys per email
  • Keys: 1-40 characters, must start with a letter, only alphanumeric and underscores (^[a-zA-Z][a-zA-Z0-9_]*$)
  • Values: 1-500 characters, no control characters (newlines, tabs, etc.)
  • Total size: 4KB maximum (JSON-encoded)
Example:
{
  "user_id": "usr_123456",
  "order_id": "ord_789012",
  "campaign": "welcome_series"
}

Response

Email accepted successfully

​
success
boolean
required
​
data
object
required
​
meta
object
required