---
title: "Send an email"
method: POST
path: "/emails"
tags: ["Emails"]
---

# Send an email

`POST /emails`

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

## Headers

- `Idempotency-Key` string

## Request body

- SendEmailRequest — 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.
  - `to` string[], required — Recipient email addresses (max 50)
  - `cc` string[], nullable — CC recipients (accepts null)
  - `bcc` string[], nullable — BCC recipients (accepts null)
  - `replyTo` string, email, nullable — Reply-to address (accepts null)
  - `subject` string, required — Email subject line
  - `html` string, nullable — HTML body content (accepts null). Maximum 5MB (5,242,880 characters). Combined with attachments, the total message must not exceed 14MB.
  - `text` string, nullable — Plain text body (accepts null, auto-generated from HTML if not provided). Maximum 5MB (5,242,880 characters).
  - `tag` string, nullable — Tag for categorization and filtering (accepts null)
  - `headers` object, nullable — Custom email headers (accepts null)
  - `attachments` Attachment[], nullable — File attachments (accepts null)
    - `filename` string, required — Attachment filename
    - `content` string, required — Base64-encoded file content
    - `contentType` string, required — MIME type
  - `metadata` Metadata, 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)

## Response `200`

Email accepted successfully

- SendEmailResponse
  - `success` true, required
  - `data` object, required
    - `id` string, required — Unique message identifier (token)
    - `messageId` string — SMTP Message-ID header value
    - `to` string[], required — List of recipient addresses
    - `status` 'pending' | 'sent', required — Current delivery status
    - `sandbox` boolean — Whether this email was sent in sandbox mode. Only present (and true) for sandbox emails sent from @arkhq.io addresses.
  - `meta` ApiMeta, required
    - `requestId` string, required — Unique request identifier for debugging and support

## Other responses

- `400` — Invalid request parameters
- `401` — Invalid or missing API key
- `402` — Payment required - insufficient credits or billing not configured. This error occurs when: - Your organization doesn't have billing configured - Your credit balance is too low to complete the request **Error codes:** - `billing_not_configured` - Set up billing at arkhq.io/org/billing - `insufficient_balance` - Add credits to continue sending - `billing_error` - Billing system error, try again
- `409` — A request with this idempotency key is already being processed
- `422` — Request understood but cannot be processed
- `429` — Too many requests. This can be either: - **Rate limit exceeded** (`rate_limit_exceeded`): Too many API requests per second. Includes `X-RateLimit-*` headers. - **Send limit exceeded** (`send_limit_exceeded`): Hourly email sending quota exceeded. Includes `X-SendLimit-*` headers. The request is rejected and no emails are sent or billed. Check the `error.code` field to distinguish between the two.
- `500` — Internal server error

---

[API](https://skmtc.net/arkhq-io/apis/ark-email-api.md) · [All operations](https://skmtc.net/arkhq-io/apis/ark-email-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arkhq-io/ark-email-api/revisions/98a90852ffca/schema)