> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nedzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Send an email

> Start an email conversation with a contact or address, or reply in one.

Send `conversationId` to reply in a conversation. Send `contactId` or `email` to start one. Send exactly one of the three.

Every plan with email can use this endpoint. The workspace needs a verified sending domain. Without one, the send is refused with `409`. See [Email](/integrations/email) to set up your domain.

<Warning>
  Every send checks Do Not Disturb (DND) first. If the contact has DND on, or the address is on the opt-out list, the send is refused with `403` and nothing is sent. If DND can't be checked, the send is refused too.
</Warning>

<ParamField body="workspaceId" type="string">
  Workspace UUID (required for account API keys, optional for workspace API keys)
</ParamField>

<ParamField body="conversationId" type="string">
  Reply in this conversation. It must be an email conversation in the workspace.
</ParamField>

<ParamField body="contactId" type="string">
  Start a conversation with this contact
</ParamField>

<ParamField body="email" type="string">
  Start a conversation with this address. Nedzo finds the contact with this address, or makes one.
</ParamField>

<ParamField body="name" type="string">
  Name for a contact this send makes. Ignored when the contact exists.
</ParamField>

<ParamField body="subject" type="string">
  The subject line. A reply keeps the thread's subject when you leave this out.
</ParamField>

<ParamField body="content" type="string" required>
  The plain text body
</ParamField>

<ParamField body="contentHtml" type="string">
  An HTML body. Nedzo cleans it before sending. `content` is the plain text version.
</ParamField>

A reply to a conversation that has ended goes into a new conversation with the same contact. The response names the conversation the message went into.

## When `messageId` is null

Sometimes the message goes out but Nedzo can't save it. The answer is still `201`, and `messageId` is `null`. The contact got the message, so don't send it again. Then `conversationId` is the conversation you sent into. If that conversation had ended, the message may have gone out on a new thread that does not show in the log.

## Errors

| Status | When |
| - | - |
| `400` | The body is not valid, or the conversation is not an email conversation |
| `402` | The account has no plan in force, no balance or messages left, the workspace hit its spend limit, or the trial has not converted |
| `403` | The contact has DND on, the contact's data is restricted, or your plan does not include email |
| `404` | The workspace, contact or conversation was not found |
| `409` | The workspace has no verified sending domain, or a send to this contact is already in progress |
| `502` | The message could not be sent. Check the conversation before you try again, in case it went out. |
| `503` | Nedzo couldn't check the workspace's limits. Nothing was sent. Try again in a moment. |

<RequestExample>
  ```bash Start theme={null}
  curl -X POST https://api.nedzo.ai/v1/conversations/email \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "email": "jane@example.com",
      "subject": "Your appointment",
      "content": "Hi Jane, your appointment is confirmed for 3pm tomorrow."
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "conversationId": "9b2f6c1e-3a4d-4e5f-8a9b-0c1d2e3f4a5b",
    "messageId": "4d1c2b3a-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  }
  ```

  ```json 409 No domain theme={null}
  {
    "type": "https://api.nedzo.ai/errors/conflict",
    "title": "Conflict",
    "status": 409,
    "detail": "Email needs a verified sending domain. Verify your domain in Settings, then try again."
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.