# Send an email

> Send transactional email from a verified domain with an idempotent request.

`POST https://api-connect.nxiom.com/api/v1/emails/send`

## Authorization

Requires `email.send`. The sender domain must be verified and allowed by the API key's domain scope.

## Headers

| Header | Required | Value |
| --- | --- | --- |
| `Authorization` | Yes | `Bearer YOUR_API_KEY` |
| `Content-Type` | Yes | `application/json` |
| `Idempotency-Key` | Yes | A stable key for this send operation |

## Body parameters

| Field | Type | Description |
| --- | --- | --- |
| `from` | string · required | Bare sender email address; use `fromName` for a display name. |
| `to` | string or string[] · required | One address, or an array of 1–100 addresses. |
| `subject` | string | Required without `templateId`; 1–500 characters. |
| `html` | string | HTML body. Provide `html`, `text`, or both; at least one is required without a template. |
| `text` | string | Plain-text body. Provide `html`, `text`, or both; at least one is required without a template. |
| `templateId` | string · optional | ID of a published template. Its subject, HTML, and text replace `subject`, `html`, and `text`. See [Templates](/docs/learn/templates). |
| `templateVariables` | object · optional | Values for the template's variables, keyed by variable name: strings, numbers, or booleans. |
| `fromName` | string · optional | Sender display name, 1–100 characters. |
| `replyTo` | string · optional | Reply-to email address. |
| `cc` | string or string[] · optional | Copy recipients. Only with one primary recipient. `to`, `cc`, and `bcc` together can have at most 50 addresses. |
| `bcc` | string or string[] · optional | Blind copy recipients. Only with one primary recipient. `to`, `cc`, and `bcc` together can have at most 50 addresses. |
| `metadata` | object · optional | Additional metadata for the send. |
| `scheduledAt` | string · optional | When to send, as an ISO 8601 timestamp with a timezone offset, such as `2026-10-05T09:00:00+01:00`. Must be in the future and at most 30 days ahead. |

## Request

### cURL

```shell
curl -X POST "https://api-connect.nxiom.com/api/v1/emails/send" \
  -H "Authorization: Bearer $NEXIOM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-user-123" \
  -d '{
  "from": "hello@mail.example.com",
  "to": "reader@example.com",
  "subject": "Welcome",
  "text": "Thanks for joining us."
}'
```

### Node.js

```typescript
import { NexiomConnect } from '@nexiom/connect';

const apiKey = process.env.NEXIOM_API_KEY;
if (!apiKey) throw new Error('Set NEXIOM_API_KEY');

const nexiom = new NexiomConnect({ apiKey });

const { data, error } = await nexiom.emails.send(
  {
    "from": "hello@mail.example.com",
    "to": "reader@example.com",
    "subject": "Welcome",
    "text": "Thanks for joining us."
  },
  { idempotencyKey: 'welcome-user-123' },
);

if (error) throw new Error(error.message);
console.log(data.messageId);
```

### PHP

```php
<?php

use Nexiom\Connect\NexiomConnect;

$apiKey = getenv('NEXIOM_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set NEXIOM_API_KEY');
}

$nexiom = new NexiomConnect($apiKey);

$email = $nexiom->emails->send(
    [
        'from' => 'hello@mail.example.com',
        'to' => 'reader@example.com',
        'subject' => 'Welcome',
        'text' => 'Thanks for joining us.',
    ],
    ['idempotencyKey' => 'welcome-user-123'],
);

echo $email['messageId'];
```

## Response

HTTP `202 Accepted`. Example identifiers below are illustrative.

`messageId` identifies the message; `deliveryIds` identify its recipient deliveries. `totalQueued` is the number queued or scheduled. `scheduledAt` is the scheduled time, or `null` for an immediate send. The Node.js and PHP SDKs unwrap the HTTP `data` object.

With `scheduledAt`, each delivery has status `scheduled` and is sent within about a minute of that time. Until then you can [reschedule](/docs/api/emails/reschedule) or [cancel](/docs/api/emails/cancel) it with its `messageId`. A scheduled send uses your sending allowance when it is sent, not when you schedule it: if your allowance is used up at that time, its deliveries become `failed` with the reason `quota_exceeded` and nothing is charged. A recipient suppressed before that time, or a key revoked since, is not sent and not charged. Your plan limits how many recipients can wait in scheduled emails at once, and a scheduled send also counts toward the daily limit of the day it is scheduled for; see [Usage limits](/docs/api/usage-limits).

Acceptance is not delivery. Follow [email.delivered](/docs/webhooks/emails/delivered), [email.bounced](/docs/webhooks/emails/bounced), and [email.failed](/docs/webhooks/emails/failed), or check [email logs](/docs/api/emails/list).

### 202 Accepted

Message queued. Track each delivery with its delivery ID.

```json
{
  "data": {
    "totalQueued": 1,
    "messageId": "message_example",
    "deliveryIds": [
      "delivery_example"
    ],
    "scheduledAt": null
  }
}
```

### 400 Bad Request

The request is invalid. Correct it before retrying; `details` lists the failing fields.

```json
{
  "error": "invalid_argument",
  "message": "Request doesn't match the schema",
  "correlationId": "req_example",
  "details": {
    "context": "body",
    "issues": []
  }
}
```

### 401 Unauthorized

The API key is missing, malformed, revoked, or expired.

```json
{
  "error": "unauthorized",
  "message": "Invalid API key",
  "correlationId": "req_example"
}
```

### 403 Forbidden

The API key lacks a required permission, or its domain restriction does not allow this sender.

```json
{
  "error": "not_allowed",
  "message": "Missing required API key permissions: email.full_access",
  "correlationId": "req_example"
}
```

### 429 Too Many Requests

Too many requests. Wait for the `Retry-After` header before retrying. A plan allowance can also return 429 with a `code`; it needs an allowance change, not a retry.

```json
{
  "error": "too_many_requests",
  "code": "RATE_LIMITED",
  "scope": "organization",
  "retryAfterSeconds": 12,
  "message": "Too many requests. Please try again later.",
  "correlationId": "req_example"
}
```

---

Source: https://connect.nxiom.com/docs/api/emails/send