Need docs with real data and keys?

Simply sign up or log in to have your API keys and real account data populated below.

プライバシーポリシー利用規約を読む

Not interested? Click here to keep reading

We created an API for programmatic access to domains, aliases, and more.

🤖

APIドキュメント

Programmatic access to your data

Email Forwarding API

Table of Contents

Libraries

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.

Language Library
Ruby Faraday
Python requests
Java OkHttp
PHP guzzle
JavaScript superagent
Node.js superagent
Go net/http
.NET RestSharp

Base URI

The current HTTP base URI path is: https://forwardemail.net:4000. It will soon change to https://api.forwardemail.net with complete backwards compatibility.

Authentication

All endpoints require your free 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.

Errors

If any errors occur, the response body of the API request will contain a detailed error message. Besides having over ten years of experience writing API's and documenting them, were inspired by Stripe's beautiful API documentation when we crafted ours 😄.

Code Name
200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
429 Too Many Requests
500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway 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.

Localization

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.

Pagination

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

Account

Create account

POST /v1/account

Body Parameter Required Type Description
email Yes String (Email) Email address
password Yes String Password

Example Request:

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

Example Response:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Password was invalid."
}

Retrieve account

GET /v1/account

Example Request:

curl -X GET https://forwardemail.net:4000/v1/account \
  -u API_TOKEN:

Example Response:

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

Update account

PUT /v1/account

Body Parameter Required Type Description
email No String (Email) Email address
given_name No String First name
family_name No String Last name
avatar_url No String (URL) Link to avatar image

Example Request:

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

Example Response:

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

Domains

Tip: Domain endpoints with a domain's name /v1/domains/:domain_name as their path are interchangable with a domain's ID :domain_id. This means you can refer to the domain by either its name or id value.

List domains

GET /v1/domains

Querystring Parameter Required Type Description
name No String (RegExp supported) Search for domains by name
alias No String (RegExp supported) Search for domains by alias name
recipient No String (RegExp supported) Search for domains by recipient

Example Request:

curl -X GET https://forwardemail.net:4000/v1/domains \
  -u API_TOKEN:

Example Response:

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

Create domain

POST /v1/domains

Body Parameter Required Type Description
domain Yes String (FQDN or IP) Fully qualified domain name ("FQDN") or IP address
plan No String (enumerable) Plan type (must be "free", "enhanced_protection", or "team", defaults to "free")

Example Request:

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

Example Response:

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

Retrieve domain

GET /v1/domains/niftylettuce.com

Example Request:

curl -X GET https://forwardemail.net:4000/v1/domains/niftylettuce.com \
  -u API_TOKEN:

Example Response:

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

Verify domain records

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

Example Request:

curl -X GET https://forwardemail.net:4000/v1/domains/niftylettuce.com/verify-records \
  -u API_TOKEN:

Example Response:

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

Update domain

PUT /v1/domains/niftylettuce.com

Body Parameter Required Type Description
smtp_port No String or Number Custom port to configure for SMTP forwarding (default is "25")

Example Request:

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

Example Response:

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

Delete domain

DELETE /v1/domains/:domain_name

Example Request:

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

Invites

Accept domain invite

GET /v1/domains/:domain_name/invites

Example Request:

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

Create domain invite

POST /v1/domains/niftylettuce.com/invites

Body Parameter Required Type Description
email Yes String (Email) Email address to invite to domain members list
group Yes String (enumerable) Group to add the user to the domain membership with (can be one of "admin" or "user")

Example Request:

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

Example Response:

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

Remove domain invite

DELETE /v1/domains/:domain_name/invites

Body Parameter Required Type Description
email Yes String (Email) Email address to remove from domain members list

Example Request:

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

Members

Update domain member

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

Body Parameter Required Type Description
group Yes String (enumerable) Group to update the user to the domain membership with (can be one of "admin" or "user")

Example Request:

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

Remove domain member

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

Example Request:

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

Aliases

Retrieve domain aliases

GET /v1/domains/niftylettuce.com/aliases

Example Request:

curl -X GET https://forwardemail.net:4000/v1/domains/niftylettuce.com/aliases \
  -u API_TOKEN:

Example Response:

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

Create new domain alias

POST /v1/domains/niftylettuce.com/aliases

Body Parameter Required Type Description
name Yes String Alias name
recipients Yes String or Array List 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)
description No String Alias description
labels No String or Array List of labels (must be line-break/space/comma separated String or Array)
is_enabled No Boolean Whether to enable to disable this alias (if disabled, emails will be routed nowhere but return successful status codes)

Example Request:

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

Example Response:

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

Update domain alias

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

Body Parameter Required Type Description
name No String Alias name
recipients Yes String or Array List 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)
description No String Alias description
labels No String or Array List of labels (must be line-break/space/comma separated String or Array)
is_enabled No Boolean Whether to enable to disable this alias (if disabled, emails will be routed nowhere but return successful status codes)

Example Request:

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

Delete domain alias

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

Example Request:

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