---
title: "Create message"
method: POST
path: "/v1/messages"
tags: ["Messages"]
---

# Create message

`POST /v1/messages`

## Request

- Base URL: `https://api.forwardemail.net`
- URL: `https://api.forwardemail.net/v1/messages`
- Auth: HTTP basic

Create/append a new message to a folder. This endpoint accepts standard Nodemailer message format and allows you to specify the target folder, initial flags, and labels. If the target folder doesn't exist, it will be created automatically.

## Request body

- MessageInput
  - `from` string, email: Sender email address
  - `to` union: Recipient email addresses
    - string
    - string[]
  - `cc` union: CC recipient email addresses
    - string
    - string[]
  - `bcc` union: BCC recipient email addresses
    - string
    - string[]
  - `subject` string: Message subject
  - `text` string: Plain text content
  - `html` string: HTML content
  - `attachments` object[]: Message attachments (Nodemailer format)
  - `folder` string: Target folder (defaults to INBOX)
  - `flags` union: IMAP flags to set on the message
    - string
    - string[]
  - `labels` union: User-defined labels to set on the message. Can be a single label string or an array of labels. Labels must start with a letter, digit, backslash, or dollar sign, and can contain word characters, dots, and hyphens. Maximum of 10 labels per message. Labels are case-insensitive and will be stored in lowercase.
    - string
    - string[]

## Response `201`

Message created successfully

- Message
  - `id` string, required: Message ID
  - `root_id` string, required: Root message ID for threading
  - `folder_id` string, required: Folder ID containing the message
  - `folder_path` string, required: Folder path containing the message
  - `thread_id` string, required: Thread ID for conversation grouping
  - `header_message_id` string, required: Message-ID header value
  - `is_unread` boolean, required: Whether message is unread
  - `is_flagged` boolean, required: Whether message is flagged
  - `is_deleted` boolean, required: Whether message is deleted
  - `is_draft` boolean, required: Whether message is a draft
  - `is_junk` boolean, required: Whether message is junk/spam
  - `is_copied` boolean, required: Whether message is copied
  - `is_encrypted` boolean, required: Whether message is encrypted (PGP/MIME or S/MIME)
  - `is_searchable` boolean, required: Whether message is searchable
  - `is_expired` boolean, required: Whether message is expired
  - `has_attachment` boolean, required: Whether message has attachments
  - `retention_date` string, date-time, nullable, required: Message retention date
  - `internal_date` string, date-time, required: Internal date (IMAP)
  - `header_date` string, date-time, required: Date from message headers
  - `subject` string, required: Message subject
  - `flags` string[], required: IMAP flags
  - `labels` string[], required: User-defined labels (lowercase, max 10)
  - `size` integer, required: Message size in bytes
  - `uid` integer, required: IMAP UID
  - `modseq` integer, required: Modification sequence
  - `transaction` string, required: Transaction type
  - `remote_address` string, required: Remote IP address
  - `created_at` string, date-time, required: Message creation timestamp
  - `updated_at` string, date-time, required: Message last update timestamp
  - `nodemailer` object: Parsed message object (included by default, set ?nodemailer=false to exclude)
  - `raw` string: Raw message content (included by default, set ?raw=false to exclude)
  - `object` 'message', required

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `500`: Internal Server Error

---

[API](https://skmtc.dev/forwardemail/apis/forward-email-api.md) · [All operations](https://skmtc.dev/forwardemail/apis/forward-email-api/llms.txt) · [OpenAPI document](https://skmtc.dev/forwardemail/apis/forward-email-api/revisions/ecefab4527f6?raw)