- Search page
- Table of Contents
Email API
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 (we are maintainers) |
Node.js | superagent (we are maintainers) |
Go | net/http |
.NET | RestSharp |
Base URI
The current HTTP base URI path is: https://api.forwardemail.net
.
Authentication
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.
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"
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
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"
Emails
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
Querystring Parameter | Required | Type | Description |
---|---|---|---|
q |
No | String (RegExp supported) | Search for emails by metadata |
domain |
No | String (RegExp supported) | Search for emails by domain name |
page |
No | Number | Page to return of results (default is 1 ) |
`limit | No | Number | Number of results per page to return (default is 50 – the max is 50 and minimum is 10 ) |
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
Body Parameter | Required | Type | Description |
---|---|---|---|
from |
No | String (Email) | The email address of the sender (must exist as an alias of the domain). |
to |
No | String or Array | Comma separated list or an Array of recipients for the "To" header. |
cc |
No | String or Array | Comma separated list or an Array of recipients for the "Cc" header. |
bcc |
No | String or Array | Comma separated list or an Array of recipients for the "Bcc" header. |
subject |
No | String | The subject of the email. |
text |
No | String or Buffer | The plaintext version of the message. |
html |
No | String or Buffer | The HTML version of the message. |
attachments |
No | Array | An array of attachment objects (see Nodemailer's common fields). |
sender |
No | String | The email address for the "Sender" header (see Nodemailer's more advanced fields). |
replyTo |
No | String | The email address for the "Reply-To" header. |
inReplyTo |
No | String | The Message-ID the message is in reply to. |
references |
No | String or Array | Space separated list or an Array of Message-ID's. |
attachDataUrls |
No | Boolean | If true then converts data: images in the HTML content of the message to embedded attachments. |
watchHtml |
No | String | An Apple Watch specific HTML version of the message (according to the Nodemailer docs, the latest watches do not require this to be set). |
amp |
No | String | An AMP4EMAIL specific HTML version of the message (see Nodemailer's example). |
icalEvent |
No | Object | An iCalendar event to use as an alternative message content (see Nodemailer's calendar events). |
alternatives |
No | Array | An Array of alternative message content (see Nodemailer's alternative content). |
encoding |
No | String | Encoding for the text and HTML strings (defaults to "utf-8" , but supports "hex" and "base64" encoding values as well). |
raw |
No | String or Buffer | A custom generated RFC822 formatted message to use (instead of one that is generated by Nodemailer – see Nodemailer's custom source). |
textEncoding |
No | String | Encoding that is forced to be used for text values (either "quoted-printable" or "base64" ). The default value is the closest value detected (for ASCII use "quoted-printable" ). |
priority |
No | String | Priority level for the email (can either be "high" , "normal" (default), or "low" ). Note that a value of "normal" does not set a priority header (this is the default behavior). If a value of "high" or "low" is set, then the X-Priority , X-MSMail-Priority , and Importance headers will be set accordingly. |
headers |
No | Object or Array | An Object or an Array of additional header fields to set (see Nodemailer's custom headers). |
messageId |
No | String | An optional Message-ID value for the "Message-ID" header (a default value will be automatically created if not set – note that the value should adhere to the RFC2822 specification). |
date |
No | String or Date | An optional Date value that will be used if the Date header is missing after parsing, otherwise the current UTC string will be used if not set. The date header cannot be more than 30 days in advance of the current time. |
list |
No | Object | An optional Object of List-* headers (see Nodemailer's list headers). |
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:
Domains
/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 |
---|---|---|---|
q |
No | String (RegExp supported) | Search for domains by name |
name |
No | String (RegExp supported) | Search for domains by name |
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
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" or the user's current paid plan if on one) |
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) |
has_adult_content_protection |
No | Boolean | Whether to enable Spam Scanner adult content protection on this domain |
has_phishing_protection |
No | Boolean | Whether to enable Spam Scanner phishing protection on this domain |
has_executable_protection |
No | Boolean | Whether to enable Spam Scanner executable protection on this domain |
has_virus_protection |
No | Boolean | Whether to enable Spam Scanner virus protection on this domain |
has_recipient_verification |
No | Boolean | Global domain default for whether to require alias recipients to click an email verification link for emails to flow through |
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
Body Parameter | Required | Type | Description |
---|---|---|---|
smtp_port |
No | String or Number | Custom port to configure for SMTP forwarding (default is "25" ) |
has_adult_content_protection |
No | Boolean | Whether to enable Spam Scanner adult content protection on this domain |
has_phishing_protection |
No | Boolean | Whether to enable Spam Scanner phishing protection on this domain |
has_executable_protection |
No | Boolean | Whether to enable Spam Scanner executable protection on this domain |
has_virus_protection |
No | Boolean | Whether to enable Spam Scanner virus protection on this domain |
has_recipient_verification |
No | Boolean | Global domain default for whether to require alias recipients to click an email verification link for emails to flow through |
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:
Invites
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
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
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 |
---|---|---|---|
q |
No | String (RegExp supported) | Search for aliases in a domain by name, label, or recipient |
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 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 |
No | String | Alias name (if not provided or if blank, then a random alias is generated) |
recipients |
No | 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 – and if not provided or is an empty Array, then the user's email making the API request will be set as the recipient) |
description |
No | String | Alias description |
labels |
No | String or Array | List of labels (must be line-break/space/comma separated String or Array) |
has_recipient_verification |
No | Boolean | Whether to enable to require recipients to click an email verification link for emails to flow through (defaults to the domain's setting if not explicitly set in the request body) |
is_enabled |
No | Boolean | Whether to enable to disable this alias (if disabled, emails will be routed nowhere but return successful status codes). Defaults to true , but if a value is passed, it is converted to a boolean using boolean) |
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
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) |
has_recipient_verification |
No | Boolean | Whether to enable to require recipients to click an email verification link for emails to flow through (defaults to the domain's setting if not explicitly set in the request body) |
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: