Email API

Right now we have not yet released any API wrappers, but we plan to do so in the near future. Send an email to api@forwardemail.net if you would like to be notified when a particular programming language's API wrapper is released. In the meanwhile, you can use these recommended HTTP request libraries in your application, or simply use curl as in the below examples.

LanguageLibrary
RubyFaraday
Pythonrequests
JavaOkHttp
PHPguzzle
JavaScriptsuperagent (we are maintainers)
Node.jssuperagent (we are maintainers)
Gonet/http
.NETRestSharp

The current HTTP base URI path is: https://api.forwardemail.net.

All endpoints require your API key to be set as the "username" value of the request's Basic Authorization header (with the exception of Alias Contacts, Alias Calendars, e Alias Mailboxes which use a generated alias username and password)..

Don't worry – examples are provided below for you if you're not sure what this is.

If any errors occur, the response body of the API request will contain a detailed error message.

CodeName
200OK
400Bad Request
401Unauthorized
403Forbidden
404Not Found
429Too Many Requests
500Internal Server Error
501Not Implemented
502Bad Gateway
503Service Unavailable
504Gateway Time-out

[!TIP] If you receive a 5xx status code (which should not happen), then please contact us at api@forwardemail.net and we will help you to resolve your issue immediately.

Our service is translated to over 25 different languages. All API response messages are translated to the last locale detected of the user making the API request. You can override this by passing a custom Accept-Language header. Feel free to try it out using the language drop-down at the bottom of this page.

[!NOTE] As of November 1st, 2024 the API endpoints for List domains e List domain aliases will default to 1000 max results per page. If you would like to opt-in to this behavior early, you can pass ?paginate=true as an additional querystring parameter to the URL for the endpoint query.

Pagination is supported by all API endpoints that list results.

Simply provide the querystring properties page (and optionally limit).

The property page should be a number greater than or equal to 1. If you provide limit (also a number), then the minimum value is 10 and maximum is 50 (unless otherwise noted).

Querystring ParameterRequiredTypeDescription
pageNoNumberPage of results to return. If not specified, the page value will be 1. Must be a number greater than or equal to 1.
limitNoNumberNumber of results to return per page. Defaults to 10 if not specified. Must be a number greater than or equal to 1, and less than or equal to 50.

In order to determine whether or not more results are available, we provide these HTTP response headers (which you can parse in order to paginate programmatically):

HTTP Response HeaderExampleDescription
X-Page-CountX-Page-Count: 3The total page count available.
X-Page-CurrentX-Page-Current: 1The current page of results returned (e.g. based off page querystring parameter).
X-Page-SizeX-Page-Size: 10The total number of results in the page returned (e.g. based off limit querystring parameter and actual results returned).
X-Item-CountX-Item-Count: 30The total number of items available across all pages.
LinkLink: <https://api.forwardemail.net/v1/emails?page=1>; rel="prev", <https://api.forwardemail.net/v1/emails?page=3>; rel="next", <https://api.forwardemail.net/v1/emails?page=3; rel="last", https://api.forwardemail.net/v1/emails?page=1; rel="first"We provide a Link HTTP response header you can parse as shown in the example. This is similar to GitHub (e.g. not all values will be provided if they are not relevant or available, e.g. "next" will not be provided if there is not another page).

Example Request:

curl https://api.forwardemail.net/v1/domains/example.com/aliases?page=2&pagination=true \
  -u API_TOKEN:

Retrieve logs

Our API programmatically allows you to download logs for your account. Submitting a request to this endpoint will process all logs for your account and email them to you as an attachment (Gzip compressed CSV spreadsheet file) once complete.

This allows you to create background jobs with a Cron job or using our Node.js job scheduling software Bree to receive logs whenever you desire. Note that this endpoint is limited to 10 requests per day.

The attachment is the lowercase form of email-deliverability-logs-YYYY-MM-DD-h-mm-A-z.csv.gz and the email itself contains a brief summary of the logs retrieved. You can also download logs at any time from My Account → Logs

GET /v1/logs/download

Querystring ParameterRequiredTypeDescription
domainNoString (FQDN)Filter logs by fully qualified domain ("FQDN"). If you do not provide this then all logs across all domains will be retrieved.
qNoStringSearch for logs by email, domain, alias name, IP address, or date (M/Y, M/D/YY, M-D, M-D-YY, or M.D.YY format).
bounce_categoryNoStringSearch for logs by a specific bounce category (e.g. blocklist).
response_codeNoNumberSearch for logs by a specific error response code (e.g. 421 or 550).

Example Request:

curl https://api.forwardemail.net/v1/logs/download \
  -u API_TOKEN:

Example Cron job (at midnight every day):

0 0 * * * /usr/bin/curl https://api.forwardemail.net/v1/logs/download -u API_TOKEN: &>/dev/null

Note that you can use services such as Crontab.guru to validate your cron job expression syntax.

Example Cron job (at midnight every day and with logs for previous day):

For MacOS:

0 0 * * * /usr/bin/curl https://api.forwardemail.net/v1/logs/download?q=`date -v-1d -u "+%-m/%-d/%y"` -u API_TOKEN: &>/dev/null

For Linux and Ubuntu:

0 0 * * * /usr/bin/curl https://api.forwardemail.net/v1/logs/download?q=`date --date "-1 days" -u "+%-m/%-d/%y"` -u API_TOKEN: &>/dev/null

Create account

POST /v1/account

Body ParameterRequiredTypeDescription
emailYesString (Email)Email address
passwordYesStringPassword

Example Request:

curl -X POST https://api.forwardemail.net/v1/account \
  -u API_TOKEN: \
  -d "email=user%40gmail.com"

Retrieve account

GET /v1/account

Example Request:

curl https://api.forwardemail.net/v1/account \
  -u API_TOKEN:

Update account

PUT /v1/account

Body ParameterRequiredTypeDescription
emailNoString (Email)Email address
given_nameNoStringFirst name
family_nameNoStringLast name
avatar_urlNoString (URL)Link to avatar image

Example Request:

curl -X PUT https://api.forwardemail.net/v1/account \
  -u API_TOKEN: \
  -d "email=user%40gmail.com"

[!NOTE] Unlike other API endpoints, these require Authentication "username" equal to the alias username and "password" equal to the alias generated password as Basic Authorization headers.

[!WARNING] This endpoint section is a work in progress and will be released (hopefully) in 2024. In the interim please use an IMAP client from the "Apps" dropdown in the navigation of our website.

List contacts

GET /v1/contacts

Coming soon

Create contact

POST /v1/contacts

Coming soon

Retrieve contact

GET /v1/contacts/:id

Coming soon

Update contact

PUT /v1/contacts/:id

Coming soon

Delete contact

DELETE /v1/contacts/:id

Coming soon

[!NOTE] Unlike other API endpoints, these require Authentication "username" equal to the alias username and "password" equal to the alias generated password as Basic Authorization headers.

[!WARNING] This endpoint section is a work in progress and will be released (hopefully) in 2024. In the interim please use an IMAP client from the "Apps" dropdown in the navigation of our website.

List calendars

GET /v1/calendars

Coming soon

Create calendar

POST /v1/calendars

Coming soon

Retrieve calendar

GET /v1/calendars/:id

Coming soon

Update calendar

PUT /v1/calendars/:id

Coming soon

Delete calendar

DELETE /v1/calendars/:id

Coming soon

[!NOTE] Unlike other API endpoints, these require Authentication "username" equal to the alias username and "password" equal to the alias generated password as Basic Authorization headers.

[!WARNING] This endpoint section is a work in progress and will be released (hopefully) in 2024. In the interim please use an IMAP client from the "Apps" dropdown in the navigation of our website.

Please ensure that you have followed setup instructions for your domain.

These instructions can be found in our FAQ section Do you support receiving email with IMAP?.

List and search for messages

GET /v1/messages

Coming soon

Create message

[!NOTE] This will NOT send an email – it will only simply add the message to your mailbox folder (e.g. this is similar to the IMAP APPEND command). If you would like to send an email, then see Create outbound SMTP email below. After creating the outbound SMTP email, then you can append a copy of it using this endpoint to your alias' mailbox for storage purposes.

POST /v1/messages

Coming soon

Retrieve message

GET /v1/messages/:id

Coming soon

Update message

PUT /v1/messages/:id

Coming soon

Delete message

DELETE /v1/messages:id

Coming soon

[!TIP] Folder endpoints with a folder's path /v1/folders/:path as their endpoint are interchangeable with a folder's ID :id. This means you can refer to the folder by either its path or id value.

[!WARNING] This endpoint section is a work in progress and will be released (hopefully) in 2024. In the interim please use an IMAP client from the "Apps" dropdown in the navigation of our website.

List folders

GET /v1/folders

Coming soon

Create folder

POST /v1/folders

Coming soon

Retrieve folder

GET /v1/folders/:id

Coming soon

Update folder

PUT /v1/folders/:id

Coming soon

Delete folder

DELETE /v1/folders/:id

Coming soon

Copy folder

POST /v1/folders/:id/copy

Coming soon

Please ensure that you have followed setup instructions for your domain.

These instructions can be found at My Account → Domains → Settings → Outbound SMTP Configuration. You need to ensure setup of DKIM, Return-Path, and DMARC for sending outbound SMTP with your domain.

Get outbound SMTP email limit

This is a simple endpoint that returns a JSON object containing the count e limit for the number of daily SMTP outbound messages on a per account basis.

GET /v1/emails/limit

Example Request:

curl https://api.forwardemail.net/v1/emails/limit \
  -u API_TOKEN:

List outbound SMTP emails

Note that this endpoint does not return property values for an email's message, headers, nor rejectedErrors.

To return those properties and their values, please use the Retrieve email endpoint with an email ID.

GET /v1/emails

Querystring ParameterRequiredTypeDescription
qNoString (RegExp supported)Search for emails by metadata
domainNoString (RegExp supported)Search for emails by domain name
sortNoStringSort by a specific field (prefix with a single hyphen - to sort in the reverse direction of that field). Defaults to created_at if not set.
pageNoNumberVeja Pagination for more insight
limitNoNumberVeja Pagination for more insight

Example Request:

curl https://api.forwardemail.net/v1/emails?limit=1 \
  -u API_TOKEN:

Create outbound SMTP email

Our API for creating an email is inspired by and leverages Nodemailer's message option configuration. Please defer to the Nodemailer message configuration for all body parameters below.

Note that with the exception of envelope e dkim (since we set those automatically for you), we support all Nodemailer options. We automatically set disableFileAccess e 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.

POST /v1/emails

Body ParameterRequiredTypeDescription
fromNoString (Email)The email address of the sender (must exist as an alias of the domain).
toNoString or ArrayComma separated list or an Array of recipients for the "To" header.
ccNoString or ArrayComma separated list or an Array of recipients for the "Cc" header.
bccNoString or ArrayComma separated list or an Array of recipients for the "Bcc" header.
subjectNoStringThe subject of the email.
textNoString or BufferThe plaintext version of the message.
htmlNoString or BufferThe HTML version of the message.
attachmentsNoArrayAn array of attachment objects (see Nodemailer's common fields).
senderNoStringThe email address for the "Sender" header (see Nodemailer's more advanced fields).
replyToNoStringThe email address for the "Reply-To" header.
inReplyToNoStringThe Message-ID the message is in reply to.
referencesNoString or ArraySpace separated list or an Array of Message-ID's.
attachDataUrlsNoBooleanIf true then converts data: images in the HTML content of the message to embedded attachments.
watchHtmlNoStringAn Apple Watch specific HTML version of the message (according to the Nodemailer docs, the latest watches do not require this to be set).
ampNoStringAn AMP4EMAIL specific HTML version of the message (see Nodemailer's example).
icalEventNoObjectAn iCalendar event to use as an alternative message content (see Nodemailer's calendar events).
alternativesNoArrayAn Array of alternative message content (see Nodemailer's alternative content).
encodingNoStringEncoding for the text and HTML strings (defaults to "utf-8", but supports "hex" e "base64" encoding values as well).
rawNoString or BufferA custom generated RFC822 formatted message to use (instead of one that is generated by Nodemailer – see Nodemailer's custom source).
textEncodingNoStringEncoding that is forced to be used for text values (either "quoted-printable" or "base64"). The default value is the closest value detected (for ASCII use "quoted-printable").
priorityNoStringPriority level for the email (can either be "high", "normal" (default), or "low"). Note that a value of "normal" does not set a priority header (this is the default behavior). If a value of "high" or "low" is set, then the X-Priority, X-MSMail-Priority, e Importance headers will be set accordingly.
headersNoObject or ArrayAn Object or an Array of additional header fields to set (see Nodemailer's custom headers).
messageIdNoStringAn optional Message-ID value for the "Message-ID" header (a default value will be automatically created if not set – note that the value should adhere to the RFC2822 specification).
dateNoString or DateAn optional Date value that will be used if the Date header is missing after parsing, otherwise the current UTC string will be used if not set. The date header cannot be more than 30 days in advance of the current time.
listNoObjectAn optional Object of List-* headers (see Nodemailer's list headers).

Example Request:

curl -X POST https://api.forwardemail.net/v1/emails \
  -u API_TOKEN: \
  -d "from=alias@example.com" \
  -d "to=user%40gmail.com" \
  -d "subject=test" \
  -d "text=test"

Example Request:

curl -X POST https://api.forwardemail.net/v1/emails \
  -u API_TOKEN: \
  -d "raw=`cat file.eml`"

Retrieve outbound SMTP email

GET /v1/emails/:id

Example Request:

curl https://api.forwardemail.net/v1/emails/:id \
  -u API_TOKEN:

Delete outbound SMTP email

Email deletion will set the status to "rejected" (and subsequently not process it in the queue) if and only if the current status is one of "pending", "queued", or "deferred". We may purge emails automatically after 30 days after they were created and/or sent – therefore you should keep a copy of outbound SMTP emails in your client, database, or application. You can reference our email ID value in your database if desired – this value is returned from both Create email e Retrieve email endpoints.

DELETE /v1/emails/:id

Example Request:

curl -X DELETE https://api.forwardemail.net/v1/emails/:id \
  -u API_TOKEN:

[!TIP] Domain endpoints with a domain's name /v1/domains/:domain_name as their endpoint are interchangeable with a domain's ID :domain_id. This means you can refer to the domain by either its name or id value.

List domains

[!NOTE] As of November 1st, 2024 the API endpoints for List domains e List domain aliases will default to 1000 max results per page. If you would like to opt-in to this behavior early, you can pass ?paginate=true as an additional querystring parameter to the URL for the endpoint query. See Pagination for more insight.

GET /v1/domains

Querystring ParameterRequiredTypeDescription
qNoString (RegExp supported)Search for domains by name
nameNoString (RegExp supported)Search for domains by name
sortNoStringSort by a specific field (prefix with a single hyphen - to sort in the reverse direction of that field). Defaults to created_at if not set.
pageNoNumberVeja Pagination for more insight
limitNoNumberVeja Pagination for more insight

Example Request:

curl https://api.forwardemail.net/v1/domains \
  -u API_TOKEN:

Create domain

POST /v1/domains

Body ParameterRequiredTypeDescription
domainYesString (FQDN or IP)Fully qualified domain name ("FQDN") or IP address
team_domainNoString (domain ID or domain name; FQDN)Automatically assign this domain to the same team from another domain. This means that all members from this domain will be assigned as team members, and the plan will automatically be set to team as well. You can set this to "none" if necessary to explicitly disable this, but that is not necessary.
planNoString (enumerable)Plan type (must be "free", "enhanced_protection", or "team", defaults to "free" or the user's current paid plan if on one)
catchallNoString (delimited email addresses) or BooleanCreate a default catch-all alias, defaults to true (if true it will use the API user's email address as a recipient, and if false no catch-all will be created). If a String is passed, then it is a delimited list of email addresses to use as recipients (separated by line break, space, and/or comma)
has_adult_content_protectionNoBooleanWhether to enable Spam Scanner adult content protection on this domain
has_phishing_protectionNoBooleanWhether to enable Spam Scanner phishing protection on this domain
has_executable_protectionNoBooleanWhether to enable Spam Scanner executable protection on this domain
has_virus_protectionNoBooleanWhether to enable Spam Scanner virus protection on this domain
has_recipient_verificationNoBooleanGlobal domain default for whether to require alias recipients to click an email verification link for emails to flow through
ignore_mx_checkNoBooleanWhether to ignore the MX record check on the domain for verification. This is mainly for users that have advanced MX exchange configuration rules and need to keep their existing MX exchange and forward to ours.
retention_daysNoNumberInteger between 0 e 30 that corresponds to the number of retention days to store outbound SMTP emails once successfully delivered or permanently errored. Defaults to 0, which means that outbound SMTP emails are purged and redacted immediately for your security.
bounce_webhookNoString (URL) or Boolean (false)The http:// or https:// webhook URL of your choice to send bounce webhooks to. We will submit a POST request to this URL with information on outbound SMTP failures (e.g. soft or hard failures – so you can manage your subscribers and programmatically manage your outbound email).
max_quota_per_aliasNoStringStorage maximum quota for aliases on this domain name. Enter a value such as "1 GB" that will be parsed by bytes.

Example Request:

curl -X POST https://api.forwardemail.net/v1/domains \
  -u API_TOKEN: \
  -d domain=example.com \
  -d plan=free

Retrieve domain

GET /v1/domains/example.com

Example Request:

curl https://api.forwardemail.net/v1/domains/example.com \
  -u API_TOKEN:

Verify domain records

GET /v1/domains/example.com/verify-records

Example Request:

curl https://api.forwardemail.net/v1/domains/example.com/verify-records \
  -u API_TOKEN:

Verify domain SMTP records

GET /v1/domains/example.com/verify-smtp

Example Request:

curl https://api.forwardemail.net/v1/domains/example.com/verify-smtp \
  -u API_TOKEN:

List domain-wide catch-all passwords

GET /v1/domains/example.com/catch-all-passwords

Example Request:

curl https://api.forwardemail.net/v1/domains/example.com/catch-all-passwords \
  -u API_TOKEN:

Create domain-wide catch-all password

POST /v1/domains/example.com/catch-all-passwords

Body ParameterRequiredTypeDescription
new_passwordNoStringYour custom new password to use for the domain-wide catch-all password. Note that you can leave this blank or missing altogether from your API request body if you wish to get a randomly generated and strong password.
descriptionNoStringDescription for organization purposes only.

Example Request:

curl BASE_URL/v1/domains/example.com/catch-all-passwords \
  -u API_TOKEN:

Remove domain-wide catch-all password

DELETE /v1/domains/example.com/catch-all-passwords/:token_id

Example Request:

curl -X DELETE https://api.forwardemail.net/v1/domains/:domain_name/catch-all-passwords/:token_id \
  -u API_TOKEN:

Update domain

PUT /v1/domains/example.com

Body ParameterRequiredTypeDescription
smtp_portNoString or NumberCustom port to configure for SMTP forwarding (default is "25")
has_adult_content_protectionNoBooleanWhether to enable Spam Scanner adult content protection on this domain
has_phishing_protectionNoBooleanWhether to enable Spam Scanner phishing protection on this domain
has_executable_protectionNoBooleanWhether to enable Spam Scanner executable protection on this domain
has_virus_protectionNoBooleanWhether to enable Spam Scanner virus protection on this domain
has_recipient_verificationNoBooleanGlobal domain default for whether to require alias recipients to click an email verification link for emails to flow through
ignore_mx_checkNoBooleanWhether to ignore the MX record check on the domain for verification. This is mainly for users that have advanced MX exchange configuration rules and need to keep their existing MX exchange and forward to ours.
retention_daysNoNumberInteger between 0 e 30 that corresponds to the number of retention days to store outbound SMTP emails once successfully delivered or permanently errored. Defaults to 0, which means that outbound SMTP emails are purged and redacted immediately for your security.
bounce_webhookNoString (URL) or Boolean (false)The http:// or https:// webhook URL of your choice to send bounce webhooks to. We will submit a POST request to this URL with information on outbound SMTP failures (e.g. soft or hard failures – so you can manage your subscribers and programmatically manage your outbound email).
max_quota_per_aliasNoStringStorage maximum quota for aliases on this domain name. Enter a value such as "1 GB" that will be parsed by bytes.

Example Request:

curl -X PUT https://api.forwardemail.net/v1/domains/example.com \
  -u API_TOKEN:

Delete domain

DELETE /v1/domains/:domain_name

Example Request:

curl -X DELETE https://api.forwardemail.net/v1/domains/:domain_name \
  -u API_TOKEN:

Accept domain invite

GET /v1/domains/:domain_name/invites

Example Request:

curl https://api.forwardemail.net/v1/domains/:domain_name/invites \
  -u API_TOKEN:

Create domain invite

POST /v1/domains/example.com/invites

Body ParameterRequiredTypeDescription
emailYesString (Email)Email address to invite to domain members list
groupYesString (enumerable)Group to add the user to the domain membership with (can be one of "admin" or "user")

Example Request:

curl -X POST https://api.forwardemail.net/v1/domains/example.com/invites \
  -u API_TOKEN: \
  -d "email=user%40gmail.com" \
  -d group=admin

[!IMPORTANT] If the user being invited is already an accepted member of any other domains the admin inviting them is a member of, then it will auto-accept the invite and not send an email.

Remove domain invite

DELETE /v1/domains/:domain_name/invites

Body ParameterRequiredTypeDescription
emailYesString (Email)Email address to remove from domain members list

Example Request:

curl -X DELETE https://api.forwardemail.net/v1/domains/:domain_name/invites \
  -u API_TOKEN:

Update domain member

PUT /v1/domains/example.com/members/:member_id

Body ParameterRequiredTypeDescription
groupYesString (enumerable)Group to update the user to the domain membership with (can be one of "admin" or "user")

Example Request:

curl -X PUT https://api.forwardemail.net/v1/domains/example.com/members/:member_id \
  -u API_TOKEN:

Remove domain member

DELETE /v1/domains/:domain_name/members/:member_id

Example Request:

curl -X DELETE https://api.forwardemail.net/v1/domains/:domain_name/members/:member_id \
  -u API_TOKEN:

Generate an alias password

Note that if you do not email instructions, then the username and password will be in the JSON response body of a successful request in the format { username: 'alias@yourdomain.com', password: 'some-generated-password' }.

POST /v1/domains/example.com/aliases/:alias_id/generate-password

Body ParameterRequiredTypeDescription
new_passwordNoStringYour custom new password to use for the alias. Note that you can leave this blank or missing altogether from your API request body if you wish to get a randomly generated and strong password.
passwordNoStringExisting password for alias to change the password without deleting the existing IMAP mailbox storage (see is_override option below if you no longer have the existing password).
is_overrideNoBooleanUSE WITH CAUTION: This will override the existing alias password and database completely, and will permanently delete the existing IMAP storage and reset the alias' SQLite email database completely. Please make a backup if possible if you have an existing mailbox attached to this alias.
emailed_instructionsNoStringEmail address to send the alias' password and setup instructions to.

Example Request:

curl -X POST https://api.forwardemail.net/v1/domains/example.com/aliases/:alias_id/generate-password \
  -u API_TOKEN:

List domain aliases

[!NOTE] As of November 1st, 2024 the API endpoints for List domains e List domain aliases will default to 1000 max results per page. If you would like to opt-in to this behavior early, you can pass ?paginate=true as an additional querystring parameter to the URL for the endpoint query. See Pagination for more insight.

GET /v1/domains/example.com/aliases

Querystring ParameterRequiredTypeDescription
qNoString (RegExp supported)Search for aliases in a domain by name, label, or recipient
nameNoString (RegExp supported)Search for aliases in a domain by name
recipientNoString (RegExp supported)Search for aliases in a domain by recipient
sortNoStringSort by a specific field (prefix with a single hyphen - to sort in the reverse direction of that field). Defaults to created_at if not set.
pageNoNumberVeja Pagination for more insight
limitNoNumberVeja Pagination for more insight

Example Request:

curl https://api.forwardemail.net/v1/domains/example.com/aliases?pagination=true \
  -u API_TOKEN:

Create new domain alias

POST /v1/domains/example.com/aliases

Body ParameterRequiredTypeDescription
nameNoStringAlias name (if not provided or if blank, then a random alias is generated)
recipientsNoString or ArrayList of recipients (must be line-break/space/comma separated String or Array of valid email addresses, fully-qualified domain names ("FQDN"), IP addresses, and/or webhook URL's – and if not provided or is an empty Array, then the user's email making the API request will be set as the recipient)
descriptionNoStringAlias description
labelsNoString or ArrayList of labels (must be line-break/space/comma separated String or Array)
has_recipient_verificationNoBooleanRequire recipients to click an email verification link for emails to flow through (defaults to the domain's setting if not explicitly set in the request body)
is_enabledNoBooleanWhether to enable or disable this alias (if disabled, emails will be routed nowhere but return successful status codes). If a value is passed, it is converted to a boolean using boolean)
error_code_if_disabledNoNumber (either 250, 421, or 550)Incoming email to this alias will reject if is_enabled is false with either 250 (quietly deliver nowhere, e.g. blackhole or /dev/null), 421 (soft reject; and retry for up to ~5 days) or 550 permanent failure and rejection. Defaults to 250.
has_imapNoBooleanWhether to enable or disable IMAP storage for this alias (if disabled, then inbound emails received will not get stored to IMAP storage. If a value is passed, it is converted to a boolean using boolean)
has_pgpNoBooleanWhether to enable or disable OpenPGP encryption adicionamos suporte para IMAP/POP3/CalDAV/CardDAV encrypted email storage using the alias' public_key.
public_keyNoStringOpenPGP public key in ASCII Armor format (click here to view an example; e.g. GPG key for support@forwardemail.net). This only applies if you have has_pgp set to true. Learn more about end-to-end encryption in our FAQ.
max_quotaNoStringStorage maximum quota for this alias. Leave blank to reset to domain current maximum quota or enter a value such as "1 GB" that will be parsed by bytes. This value can only be adjusted by domain admins.
vacation_responder_is_enabledNoBooleanWhether to enable or disable an automatic vacation responder.
vacation_responder_start_dateNoStringStart date for vacation responder (if enabled and no start date set here, then it assumes it is already started). We support date formats such as MM/DD/YYYY, YYYY-MM-DD, and other date formats via smart parsing using dayjs.
vacation_responder_end_dateNoStringEnd date for vacation responder (if enabled and no end date set here, then it assumes it never ends and responds forever). We support date formats such as MM/DD/YYYY, YYYY-MM-DD, and other date formats via smart parsing using dayjs.
vacation_responder_subjectNoStringSubject in plaintext for the vacation responder, e.g. "Out of Office". We use striptags to remove all HTML here.
vacation_responder_messageNoStringMessage in plaintext for the vacation responder, e.g. "I will be out of office until February.". We use striptags to remove all HTML here.

Example Request:

curl -X POST https://api.forwardemail.net/v1/domains/example.com/aliases \
  -u API_TOKEN:

Retrieve domain alias

You can retrieve a domain alias by either its id or its name value.

GET /v1/domains/:domain_name/aliases/:alias_id

Example Request:

curl https://api.forwardemail.net/v1/domains/:domain_name/aliases/:alias_id \
  -u API_TOKEN:

GET /v1/domains/:domain_name/aliases/:alias_name

Example Request:

curl https://api.forwardemail.net/v1/domains/:domain_name/aliases/:alias_name \
  -u API_TOKEN:

Update domain alias

PUT /v1/domains/example.com/aliases/:alias_id

Body ParameterRequiredTypeDescription
nameNoStringAlias name
recipientsNoString or ArrayList of recipients (must be line-break/space/comma separated String or Array of valid email addresses, fully-qualified domain names ("FQDN"), IP addresses, and/or webhook URL's)
descriptionNoStringAlias description
labelsNoString or ArrayList of labels (must be line-break/space/comma separated String or Array)
has_recipient_verificationNoBooleanRequire recipients to click an email verification link for emails to flow through (defaults to the domain's setting if not explicitly set in the request body)
is_enabledNoBooleanWhether to enable or disable this alias (if disabled, emails will be routed nowhere but return successful status codes). If a value is passed, it is converted to a boolean using boolean)
error_code_if_disabledNoNumber (either 250, 421, or 550)Incoming email to this alias will reject if is_enabled is false with either 250 (quietly deliver nowhere, e.g. blackhole or /dev/null), 421 (soft reject; and retry for up to ~5 days) or 550 permanent failure and rejection. Defaults to 250.
has_imapNoBooleanWhether to enable or disable IMAP storage for this alias (if disabled, then inbound emails received will not get stored to IMAP storage. If a value is passed, it is converted to a boolean using boolean)
has_pgpNoBooleanWhether to enable or disable OpenPGP encryption adicionamos suporte para IMAP/POP3/CalDAV/CardDAV encrypted email storage using the alias' public_key.
public_keyNoStringOpenPGP public key in ASCII Armor format (click here to view an example; e.g. GPG key for support@forwardemail.net). This only applies if you have has_pgp set to true. Learn more about end-to-end encryption in our FAQ.
max_quotaNoStringStorage maximum quota for this alias. Leave blank to reset to domain current maximum quota or enter a value such as "1 GB" that will be parsed by bytes. This value can only be adjusted by domain admins.
vacation_responder_is_enabledNoBooleanWhether to enable or disable an automatic vacation responder.
vacation_responder_start_dateNoStringStart date for vacation responder (if enabled and no start date set here, then it assumes it is already started). We support date formats such as MM/DD/YYYY, YYYY-MM-DD, and other date formats via smart parsing using dayjs.
vacation_responder_end_dateNoStringEnd date for vacation responder (if enabled and no end date set here, then it assumes it never ends and responds forever). We support date formats such as MM/DD/YYYY, YYYY-MM-DD, and other date formats via smart parsing using dayjs.
vacation_responder_subjectNoStringSubject in plaintext for the vacation responder, e.g. "Out of Office". We use striptags to remove all HTML here.
vacation_responder_messageNoStringMessage in plaintext for the vacation responder, e.g. "I will be out of office until February.". We use striptags to remove all HTML here.

Example Request:

curl -X PUT https://api.forwardemail.net/v1/domains/example.com/aliases/:alias_id \
  -u API_TOKEN:

Delete domain alias

DELETE /v1/domains/:domain_name/aliases/:alias_id

Example Request:

curl -X DELETE https://api.forwardemail.net/v1/domains/:domain_name/aliases/:alias_id \
  -u API_TOKEN:

We allow you to encrypt records even on the free plan at no cost. Privacy should not be a feature, it should be inherently built-in to all aspects of a product. As highly requested in a discussão do Privacy Guides e em nossas issues do GitHub we've added this.

Encrypt TXT Record

POST /v1/encrypt

Body ParameterRequiredTypeDescription
inputYesStringAny valid Forward Email plaintext TXT record

Example Request:

curl -X POST https://api.forwardemail.net/v1/encrypt \
  -d "input=user@gmail.com"