---
title: "Create outbound SMTP email"
method: POST
path: "/v1/emails"
tags: ["Emails"]
---

# Create outbound SMTP email

`POST /v1/emails`

## Request

- Base URL: `https://api.forwardemail.net`
- URL: `https://api.forwardemail.net/v1/emails`
- Auth: one of:
  - HTTP basic
  - HTTP basic

Our API for creating an email is inspired by and leverages Nodemailer's message option configuration. Please defer to the [Nodemailer message configuration](https://nodemailer.com/message/) for all body parameters below.

Note that with the exception of `envelope` and `dkim` (since we set those automatically for you), we support all Nodemailer options. We automatically set `disableFileAccess` and `disableUrlAccess` options to `true` for security purposes.

You should either pass the single option of `raw` with your raw full email including headers or pass individual body parameter options below.

This API endpoint will automatically encode emojis for you if they are found in the headers (e.g. a subject line of `Subject: 🤓 Hello` gets converted to `Subject: =?UTF-8?Q?=F0=9F=A4=93?= Hello` automatically). Our goal was to make an extremely developer-friendly and dummy-proof email API.

**Scheduled Sending:** To schedule an email for future delivery, set the `date` field to a future timestamp (must be at least 1 minute ahead and no more than 30 days from now). The email will be held until the specified time. You can cancel it using the Delete email endpoint.

**Authentication:** This endpoint supports both API token authentication and alias credentials authentication. You can authenticate using either your API key (recommended) or your alias email address and generated password. See the Authentication section in the API documentation for details.

A domain's catch-all password also works here, with any address on the domain as the username. It can only send: the email is sent as the domain admin who generated the password, the From address can be any address on the domain, and the login cannot be used with any other endpoint.

## Request body

- SMTP
  - `from` string, email: The email address of the sender (must exist as an alias of the domain).
  - `to` union: Comma-separated list or an array of recipients for the 'To' header.
    - string
    - string[]
  - `cc` union: Comma-separated list or an array of recipients for the 'Cc' header.
    - string
    - string[]
  - `bcc` union: Comma-separated list or an array of recipients for the 'Bcc' header.
    - string
    - string[]
  - `subject` string: The subject of the email.
  - `text` string: The plaintext version of the message.
  - `html` string: The HTML version of the message.
  - `attachments` object[]: An array of attachment objects (see Nodemailer's common fields).
  - `sender` string, email: The email address for the 'Sender' header.
  - `replyTo` string, email: The email address for the 'Reply-To' header.
  - `inReplyTo` string: The Message-ID the message is in reply to.
  - `references` union: Space-separated list or an array of Message-IDs.
    - string
    - string[]
  - `attachDataUrls` boolean: If true, converts data: images in the HTML content to embedded attachments.
  - `watchHtml` string: Apple Watch specific HTML version of the message.
  - `amp` string: AMP4EMAIL specific HTML version of the message.
  - `icalEvent` object: An iCalendar event as an alternative message content.
  - `alternatives` object[]: An array of alternative message content.
  - `encoding` string: Encoding for the text and HTML strings (e.g., 'utf-8', 'hex', 'base64').
  - `raw` string: Custom generated RFC822 formatted message (instead of using Nodemailer generation).
  - `textEncoding` 'quoted-printable' | 'base64': Encoding forced to be used for text values.
  - `priority` 'high' | 'normal' | 'low': Priority level for the email.
  - `headers` union: Object or array of additional header fields.
    - object
    - object[]
  - `messageId` string: Optional Message-ID for the 'Message-ID' header.
  - `date` union: Optional Date header. If set to a future time (more than 1 minute ahead), the email will be held until that time. Cannot be more than 30 days in the future from creation.
    - string, date-time
    - string
  - `list` object: Optional object of List-* headers.
  - `requireTLS` boolean: If true, requires TLS for the entire delivery chain (RFC 8689). The message will only be transmitted over TLS-encrypted connections.

## Response `200`

Email sent successfully

- object
  - `message` string

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden

---

[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)