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.

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, and 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.

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 and 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).

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

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

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

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

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.

WIP: 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.

NOTE: CardDAV support is not yet available, follow this discussion on GitHub for updates.

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.

WIP: 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.

WIP: 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

WIP: 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 and 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

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 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.

POST /v1/emails

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 and Retrieve email endpoints.

DELETE /v1/emails/:id

Example Request:

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

List domains

NOTE: As of November 1st, 2024 the API endpoints for List domains and 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 Request:

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

Create domain

POST /v1/domains

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:

Update domain

PUT /v1/domains/example.com

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

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

Remove domain invite

DELETE /v1/domains/:domain_name/invites

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

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

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 and 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

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

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

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 Privacy Guides discussion and on our GitHub issues we've added this.

Encrypt TXT Record

POST /v1/encrypt

Example Request:

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