Skip to main content
POST
/
conversations
/
compose
Create a new conversation
curl --request POST \
  --url https://api.getfernand.com/conversations/compose \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "channel_id": 123,
  "content": {
    "content": "<string>",
    "attachments": [
      {
        "name": "<string>",
        "type": "<string>",
        "content": "aSDinaTvuI8gbWludGxpZnk="
      }
    ],
    "actions": [
      {
        "name": "<string>",
        "data": {},
        "snippet_id": 123
      }
    ]
  }
}
'
{
  "id": "m-123456",
  "conversation_id": 12345,
  "type": "MESSAGE",
  "timestamp": "2026-01-21T14:30:00Z",
  "way": "IN",
  "status": "SENT",
  "source": "EMAIL",
  "download_url": "https://api.getfernand.com/conversations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/original.eml?token=abc123",
  "agent_id": 42,
  "contact_id": 789,
  "message": "<p>Hello, I need help with my account.</p>",
  "attachments": [
    {
      "id": 123,
      "name": "<string>",
      "url": "<string>",
      "type": "<string>",
      "size": 123,
      "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ],
  "delay": 0,
  "unsubscribe_url": "https://newsletter.hooli.com/unsubscribe?token=xyz789",
  "last_event": {
    "event": "DELIVERED",
    "received_at": "2026-01-21T14:31:00Z",
    "error_code": "550",
    "reason": "Message delivered successfully"
  },
  "actions": [
    {}
  ],
  "language": "en",
  "is_read": false,
  "is_automated": false
}
Creates a new conversation and sends an email message to specified recipients. Supports attachments, delayed sending, and automated actions via snippets. The email is sent from the specified channel and can include to, cc, and bcc recipients.

Authorizations

​
X-API-Key
string
header
required

Authenticate your account by including your secret key in API requests. You can manage your API keys in the Dashboard.

Authentication to the API is performed by using the HTTP Header X-API-Key.

Body

application/json
​
channel_id
integer<int64>
required

ID of the channel to send from (determines the sender email address).

​
content
object
required

Email content and metadata.

​
to
string

Comma-separated list of recipient email addresses (can include names like "Monica Hall monica.hall@raviga-capital.com").

​
cc
string

Comma-separated list of CC recipient email addresses (optional).

​
bcc
string

Comma-separated list of BCC recipient email addresses (optional).

​
subject
string

Subject line of the email (optional).

Maximum string length: 150
​
delay
integer
default:7

Delay in seconds before sending the email (0-86400, default 7 seconds).

Required range: 0 <= x <= 86400
​
agent_id
integer<int64>

ID of the agent sending this email (required, to know which agent will be the sender).

​
agent_email
string

Email of the agent sending this email (required if agent_id is not provided).

​
generated_id
string

Client-generated ID to track the message in the response (optional, returned unchanged).

Response

Message sent successfully.

​
id
string
required

Unique identifier for the message

Example:

"m-123456"

​
conversation_id
integer<int64>
required

ID of the conversation this message belongs to

Example:

12345

​
type
enum<string>
required

Type of entry (always MESSAGE for messages)

Available options:
MESSAGE
Example:

"MESSAGE"

​
timestamp
string<date-time>
required

ISO 8601 timestamp when the message was created

Example:

"2026-01-21T14:30:00Z"

​
way
enum<string>
required

Direction of the message (IN for incoming, OUT for outgoing)

Available options:
IN,
OUT
Example:

"IN"

​
status
enum<string>
required

Current status of the message

Available options:
DRAFT,
PENDING,
SENT,
RECEIVED,
BOUNCED,
SPAM,
ERROR
Example:

"SENT"

​
source
enum<string>
required

Source channel of the message

Available options:
EMAIL,
CHAT
Example:

"EMAIL"

​
download_url
string | null

URL to download the original email file (.eml), if available

Example:

"https://api.getfernand.com/conversations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/original.eml?token=abc123"

​
agent_id
integer<int64> | null

ID of the agent who sent the message (null for incoming messages)

Example:

42

​
contact_id
integer<int64> | null

ID of the contact who sent the message (null for outgoing messages)

Example:

789

​
message
string

HTML content of the message body

Example:

"<p>Hello, I need help with my account.</p>"

​
attachments
object[]

Array of file attachments in the message

​
delay
integer<int32>

Delay in seconds before the message is sent (for scheduled messages)

Example:

0

​
unsubscribe_url
string | null

URL for the recipient to unsubscribe, if available

Example:

"https://newsletter.hooli.com/unsubscribe?token=xyz789"

​
last_event
object

Most recent delivery event for this message

​
actions
object[]

Array of automated actions triggered by this message

​
language
string | null

Detected language code of the message content (e.g., en, fr, es)

Example:

"en"

​
is_read
boolean

Whether the message has been read by the recipient (chat messages only)

Example:

false

​
is_automated
boolean

Whether this message was sent automatically by the system

Example:

false