> ## Documentation Index > Fetch the complete documentation index at: https://developers.getfernand.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a new conversation 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. ## OpenAPI ````yaml https://api.getfernand.com/openapi.json post /conversations/compose openapi: 3.0.3 info: title: Fernand API Documentation version: '3.0' description: This is the documentation for the [Fernand](https://getfernand.com) API. termsOfService: https://getfernand.com/terms contact: name: Fernand Support url: https://getfernand.com email: support@getfernand.com x-logo: url: https://app.getfernand.com/images/favicon/icon_128.png servers: - url: https://api.getfernand.com description: '' x-last-modified: 1764750693905 security: - apiKeyHeader: [] externalDocs: description: You can access our documentation online by visiting https://api.fernand.help url: https://api.fernand.help paths: /conversations/compose: post: tags: - Conversations summary: Create a new conversation description: >- 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. operationId: composeEmail requestBody: required: true content: application/json: schema: type: object properties: channel_id: type: integer format: int64 description: >- ID of the channel to send from (determines the sender email address). to: type: string description: >- Comma-separated list of recipient email addresses (can include names like `Monica Hall `). cc: type: string description: >- Comma-separated list of CC recipient email addresses (optional). bcc: type: string description: >- Comma-separated list of BCC recipient email addresses (optional). subject: type: string maxLength: 150 description: Subject line of the email (optional). content: type: object description: Email content and metadata. properties: content: type: string description: HTML content of the email body (required). attachments: type: array items: type: object properties: name: type: string description: Filename of the attachment. type: type: string description: MIME type of the attachment. content: type: string format: byte description: Base64-encoded file content (max 5MB per file). description: Array of file attachments (optional). actions: type: array items: type: object properties: name: type: string description: >- Name of the action to execute (e.g., teammates.assign, status.close). data: type: object description: Action-specific parameters. snippet_id: type: integer description: >- ID of the snippet this action came from (for tracking). description: Automated actions to execute after sending (optional). delay: type: integer minimum: 0 maximum: 86400 default: 7 description: >- Delay in seconds before sending the email (0-86400, default 7 seconds). agent_id: type: integer format: int64 description: >- ID of the agent sending this email (required, to know which agent will be the sender). agent_email: type: string description: >- Email of the agent sending this email (required if agent_id is not provided). generated_id: type: string description: >- Client-generated ID to track the message in the response (optional, returned unchanged). required: - channel_id - content responses: '200': description: Message sent successfully. content: application/json: schema: $ref: '#/components/schemas/Message' '202': description: Actions were executed but no message was sent (action-only request). content: application/json: schema: type: object '400': description: Invalid input, missing recipients, or attachments too large. content: application/json: schema: type: object properties: error: type: string '403': description: >- Missing required permission (Selected agent doesn't have the right to send). content: application/json: schema: type: object properties: error: type: string '404': description: Channel or agent not found, or organization expired. content: application/json: schema: type: object properties: error: type: string '429': description: Rate limit exceeded (too many requests in a short time). content: application/json: schema: type: object properties: error: type: string components: schemas: Message: type: object properties: id: type: string description: Unique identifier for the message example: m-123456 conversation_id: type: integer format: int64 description: ID of the conversation this message belongs to example: 12345 type: type: string enum: - MESSAGE description: Type of entry (always MESSAGE for messages) example: MESSAGE download_url: type: string nullable: true description: 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 timestamp: type: string format: date-time description: ISO 8601 timestamp when the message was created example: '2026-01-21T14:30:00Z' agent_id: type: integer format: int64 nullable: true description: ID of the agent who sent the message (null for incoming messages) example: 42 way: type: string enum: - IN - OUT description: Direction of the message (IN for incoming, OUT for outgoing) example: IN contact_id: type: integer format: int64 nullable: true description: ID of the contact who sent the message (null for outgoing messages) example: 789 message: type: string description: HTML content of the message body example:

Hello, I need help with my account.

attachments: type: array items: $ref: '#/components/schemas/Attachment' description: Array of file attachments in the message status: type: string enum: - DRAFT - PENDING - SENT - RECEIVED - BOUNCED - SPAM - ERROR description: Current status of the message example: SENT delay: type: integer format: int32 description: Delay in seconds before the message is sent (for scheduled messages) example: 0 source: type: string enum: - EMAIL - CHAT description: Source channel of the message example: EMAIL unsubscribe_url: type: string nullable: true description: URL for the recipient to unsubscribe, if available example: https://newsletter.hooli.com/unsubscribe?token=xyz789 last_event: allOf: - $ref: '#/components/schemas/MessageEvent' nullable: true description: Most recent delivery event for this message actions: type: array items: type: object description: Array of automated actions triggered by this message language: type: string nullable: true description: Detected language code of the message content (e.g., en, fr, es) example: en is_read: type: boolean description: >- Whether the message has been read by the recipient (chat messages only) example: false is_automated: type: boolean description: Whether this message was sent automatically by the system example: false required: - id - conversation_id - type - timestamp - way - status - source x-computed-hash: f06a9fad859d70eed1fa800c0c475119662f50b53898da1b3e6443b836ce35be x-last-modified: 1773150592 Attachment: type: object properties: id: type: integer format: int64 description: Unique identifier for the attachment name: type: string maxLength: 250 description: Name of the attachment file url: type: string format: uri description: Download URL for the attachment type: type: string maxLength: 250 description: MIME type of the attachment (content_type) size: type: integer format: int32 description: Size of the attachment in bytes uuid: type: string format: uuid description: Unique UUID for the attachment required: - id - name - url - type - size - uuid x-computed-hash: e3f6f020dd720737f6114ca84de8255a075145ec2af171dfba4f88f71cfb4490 x-last-modified: 1769075324 MessageEvent: type: object properties: event: type: string enum: - QUEUED - CANCELED - DELIVERED - RECEIVED - SOFT_BOUNCE - HARD_BOUNCE - REJECTED - SPAM - ERROR description: Type of delivery event example: DELIVERED error_code: type: string maxLength: 10 nullable: true description: Error code if the event represents a failure example: '550' reason: type: string maxLength: 250 nullable: true description: Human-readable description of the event or error example: Message delivered successfully received_at: type: string format: date-time description: ISO 8601 timestamp when the event was received example: '2026-01-21T14:31:00Z' required: - event - received_at x-computed-hash: 91b9f7e32e29a071b0d7ea10809ffe841a3ac3f59acecfdf33716d2010e8de35 x-last-modified: 1769075324 securitySchemes: apiKeyHeader: type: apiKey description: >- Authenticate your account by including your secret key in API requests. You can manage your API keys in the [Dashboard](https://app.getfernand.com/). Authentication to the API is performed by using the HTTP Header X-API-Key. name: X-API-Key in: header x-last-modified: 1764750344730 ````