---
title: "Send Email"
method: POST
path: "/v1/sending"
tags: ["Emails"]
---

# Send Email

`POST /v1/sending`

Send one generated email to a single recipient, audience, segment, or tag. Provide emailId to send a specific email from a conversation or series. conversationId remains supported for single-email conversations. All sends are queued for background delivery and return immediately with status queued. Single-recipient sends are transactional by default; batch sends default to marketing. Requires API key with email:send.

## Headers

- `Idempotency-Key` string

## Request body

- SendEmailRequest
  - `recipientType` 'email' | 'audience' | 'segment' | 'tag', required — Type of recipient. 'email' for single send, 'audience' or 'segment' for segment-based batch sends, 'tag' for tag-based batch sends.
  - `recipientId` string — Required for audience/segment/tag sends. The segment or tag ID.
  - `recipientEmail` string, email — Required for single email sends.
  - `from` string, email, required — Sender email address (must be from a verified domain)
  - `fromName` string, required — Sender display name
  - `replyTo` string, email
  - `subject` string, required
  - `variables` object — Template variables for personalization
  - `providerType` 'ses' | 'resend' | 'sendgrid' | 'mailgun' | 'migma' — Email service provider to send through. Defaults to Migma's built-in sending. To use an external provider, connect it first in Settings → Integrations → Email Providers.
  - `projectId` string — Project ID. Optional when emailId or conversationId resolves the project automatically.
  - `conversationId` string — Conversation ID from a generated email. Works for single-email conversations. For series, use emailId.
  - `transactional` boolean — Controls whether the email is treated as transactional (order confirmations, password resets) or marketing. Defaults to true for single sends (recipientType 'email') and false for batch sends (recipientType 'audience', 'segment', 'tag'). Transactional emails bypass subscription status and topic preference filters, and omit List-Unsubscribe headers. Bounced and invalid addresses are always excluded. Set explicitly to override the default.
  - `emailId` string — Generated email ID from result.emails[].emailId. Recommended for all generated emails and required for series slots.

## Response `200`

Email sent or batch queued

- ApiResponseSendEmail
  - `success` boolean, required
  - `data` object, nullable
    - `id` string — Message ID (for single sends) or batch ID (for batch sends)
    - `provider` string
    - `status` string — sent, queued, or processing
    - `sentCount` integer
    - `message` string
    - `sendId` string — Real tracking id for a single send. Use it with the email metrics/logs endpoints and the activity view. Absent for batch sends.
    - `batchId` string — Batch id for an audience/tag send. Absent for single sends.
    - `emailId` string — Echoes the generated email id this send was tagged with, when provided. Use it to query this email's performance across every API send.
    - `conversationId` string — Conversation this send belongs to, when known.
  - `error` string, nullable

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden - Missing required permissions or access denied
- `409` — Conflict - the Idempotency-Key was reused with a different request body (code: IDEMPOTENCY_CONFLICT)

---

[API](https://skmtc.net/migma/apis/migma-ai-api-v1.md) · [All operations](https://skmtc.net/migma/apis/migma-ai-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/migma/migma-ai-api-v1/versions/3f3dba69574b/schema)