Email Forwarding API

Table of Contents

• Libraries
• Base URI
• Authentication
• Errors
• Localization
• Pagination
• Account
  • Create account
  • Retrieve account
  • Update account
• Domains
  • List domains
  • Create domain
  • Retrieve domain
  • Verify domain records
  • Update domain
  • Delete domain
• Invites
  • Accept domain invite
  • Create domain invite
  • Remove domain invite
• Members
  • Update domain member
  • Remove domain member
• Aliases
  • List domain aliases
  • Create new domain alias
  • Retrieve domain alias
  • Update domain alias
  • Delete domain alias

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://api.forwardemail.net. The legacy HTTP base URI path of https://forwardemail.net:4000 is deprecated as of January 1, 2021.

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.

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

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://api.forwardemail.net/v1/account \
  -u API_TOKEN: \
  -d "email=user%40gmail.com"

Example Response:

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

Retrieve account

GET /v1/account

Example Request:

curl -X GET https://api.forwardemail.net/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://api.forwardemail.net/v1/account \
  -u API_TOKEN: \
  -d "email=user%40gmail.com"

Example Response:

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

Domains

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://api.forwardemail.net/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")
catchall	No	String (delimited email addresses) or Boolean	Create 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)

Example Request:

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

Example Response:

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

Retrieve domain

GET /v1/domains/example.com

Example Request:

curl -X GET 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 -X GET 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

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://api.forwardemail.net/v1/domains/example.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://api.forwardemail.net/v1/domains/:domain_name \
  -u API_TOKEN:

Invites

Accept domain invite

GET /v1/domains/:domain_name/invites

Example Request:

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

Create domain invite

POST /v1/domains/example.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://api.forwardemail.net/v1/domains/example.com/invites \
  -u API_TOKEN: \
  -d "email=user%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://api.forwardemail.net/v1/domains/:domain_name/invites \
  -u API_TOKEN:

Members

Update domain member

PUT /v1/domains/example.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://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:

Aliases

List domain aliases

GET /v1/domains/example.com/aliases

Querystring Parameter	Required	Type	Description
name	No	String (RegExp supported)	Search for aliases in a domain by name
recipient	No	String (RegExp supported)	Search for aliases in a domain by recipient

Example Request:

curl -X GET 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

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://api.forwardemail.net/v1/domains/example.com/aliases \
  -u API_TOKEN:

Example Response:

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

Example Response:

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

Update domain alias

PUT /v1/domains/example.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://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: