ARarkhq-io
Emails

Send an email

Changed on

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

Request

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

Changes

  • e38e03901debRevision changes
    • warning

      the optional response header X-RateLimit-Limit removed for the status 429

    • warning

      the optional response header X-RateLimit-Remaining removed for the status 429

    • warning

      the optional response header X-RateLimit-Reset removed for the status 429

  • 37bce0c9a4d7Revision changes
    • warning

      added the new infrastructure_error enum value to the / response property for the response status

    • warning

      added the new infrastructure_error enum value to the / response property for the response status

    • warning

      added the new infrastructure_error enum value to the / response property for the response status

    • warning

      added the new infrastructure_error enum value to the / response property for the response status

    • warning

      added the new infrastructure_error enum value to the / response property for the response status

    • warning

      added the new infrastructure_error enum value to the / response property for the response status

    • warning

      added the new infrastructure_error enum value to the / response property for the response status

    • info

      removed the postal_error enum value from the / response property for the response status

    • info

      removed the postal_error enum value from the / response property for the response status

    • info

      removed the postal_error enum value from the / response property for the response status

    • info

      removed the postal_error enum value from the / response property for the response status

    • info

      removed the postal_error enum value from the / response property for the response status

    • info

      removed the postal_error enum value from the / response property for the response status

    • info

      removed the postal_error enum value from the / response property for the response status