Email Forwarding API

Libraries
Base URI
Authentication
Errors
Localization
Pagination
Account
Domains
Invites
Members
- Update domain member
- Remove domain member
Aliases

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 will be deprecated on 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. 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://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

Tip: Domain endpoints with a domain's name /v1/domains/:domain_name as their path 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

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

Retrieve domain aliases

GET /v1/domains/example.com/aliases

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

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:

Need docs with real data and keys?

API Documentation

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

Retrieve domain aliases

Create new domain alias

Update domain alias

Delete domain alias