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

If you would like to be notified when pagination is available, then please email api@forwardemail.net.

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:

Example Response:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid 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"

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.

List emails

Note that this endpoint does not return an already created email's message, headers, accepted, nor rejectedErrors properties.

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

This endpoint will return at most 50 results at a time. If you want to query for multiple pages, then append ?page=NUMBER where NUMBER is an integer, e.g. ?page=1.

GET /v1/emails

Example Request:

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

Example Response:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid API token."
}

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

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 email

GET /v1/emails/:id

Example Request:

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

Example Response:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid API token."
}

Delete 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

GET /v1/domains

Example Request:

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

Example Response:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid 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:

Example Response:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid 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:

Example Response:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid 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:

List domain aliases

GET /v1/domains/example.com/aliases

Example Request:

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

Example Response:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid 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: