Sign in

v49

latestOpenAPI 3.1.0Proprietaryraw.githubusercontent.com2026-02-185890337.1 KB
Emails

Send an email

Send a single email message. The email is accepted for immediate delivery and typically delivered within seconds.

Example use case: Send a password reset email to a user.

Required fields: from, to, subject, and either html or text

Idempotency: Supports Idempotency-Key header for safe retries.

Related endpoints:

  • GET /emails/{emailId} - Track delivery status
  • GET /emails/{emailId}/deliveries - View delivery attempts
  • POST /emails/{emailId}/retry - Retry failed delivery
post/emails

Headers

Idempotency-Keystring

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

Request body

fromstring 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.

tostring[] required

Recipient email addresses (max 50)

ccstring[] nullable

CC recipients (accepts null)

bccstring[] nullable

BCC recipients (accepts null)

replyTostring email nullable

Reply-to address (accepts null)

subjectstring required

Email subject line

htmlstring nullable

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

textstring nullable

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

tagstring nullable

Tag for categorization and filtering (accepts null)

headersobject nullable

Custom email headers (accepts null)

metadataMetadata nullable

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 request

{
  "from": "Acme <hello@acme.com>",
  "to": [
    "user@example.com"
  ],
  "subject": "Hello World",
  "html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
  "metadata": {
    "user_id": "usr_123456",
    "campaign": "welcome_series"
  }
}

Response

Email accepted successfully

successtrue required

Example response

{
  "data": {
    "id": "aBc123XyZ456",
    "messageId": "<abc123@mail.arkhq.io>"
  },
  "meta": {
    "requestId": "req_V1StGXR8_Z5jdHi6"
  }
}