/ Guides / Accounts & onboarding / Manage email domains

Manage email domains

Get a list of all email domains associated with your account, approve new email domains, and get a list of approved email domains.

How it works

An email domain is the part of an email address that comes after the @ symbol. Your list of email domains will contain all the domains that have been supplied as part of people's email addresses. It is automatically populated and can't be modified.

An approved email domain is an email domain that can be supplied as part of someone's email address when you create a person. If you're using a product-level API key, your list of approved email domains will be empty by default if no approved email domains have been added by you. You can choose to add domain(s) to your list in order to enable this security feature. If you're using a user-level API key, this feature is enabled by default.

For example, if your list of approved email domains only includes @example.com, then:

  • you'll be able create a person whose email address is jane.doe@example.com
  • you won't be able to create a person whose email address is jane.doe@otherexample.com and will receive a 400 error instead

To use @otherexample.com, you'll need to update your list of approved email domains.

info

You can also remove an approved email domain by updating your list. This won't affect any existing people who use that domain.

List email domains

Get/v2/accounts/{accountId}/people/email-domains

Request

Use this request to retrieve a list of email domains used by people on your account. You can then use the results to update your approved domains.

Sample requestRequest structure
Copy
Copied
curl -i -X GET \
  'https://api.equalsmoney.com/v2/accounts/F12345/people/email-domains' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
Copy
Copied
curl -i -X GET \
  'https://api.equalsmoney.com/v2/accounts/{accountId}/people/email-domains' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE'

Path parameters

Parameter Description
accountId
string
required		 The ID of the account that you want to retrieve a list of email domains for.

Allowable values:
An existing accountId (<= 36 characters)

Response

If your request is successful, you'll receive a 200 response containing a list of the email domains that are currently associated with your account.

Sample responseResponse structure
Copy
Copied
{
  "count": 1,
  "limit": 100,
  "offset": 0,
  "rows": [
    {
      "id": "8e214819-5c83-429f-a976-eb127a0a8a88",
      "accountId": "F12345",
      "name": "equalsmoney.com",
      "createdAt": "2023-01-30T08:30:00Z",
      "updatedAt": "2023-01-30T08:30:00Z"
    }
  ]
}
Copy
Copied
{
  "count": integer,
  "limit": integer,
  "offset": integer,
  "rows": [
    {
      "id": "string",
      "accountId": "string",
      "name": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}

For more detailed information about this request and its response, see the API reference.

Update approved email domains

Put/v2/accounts/{accountId}/email-domains

Request

Use this request to update the list of approved email domains associated with a given account. You'll only be able to create people if their email address contains one of the domains in this list.

Sample requestRequest structure
Copy
Copied
curl -i -X PUT \
  'https://api.equalsmoney.com/v2/accounts/F12345/email-domains' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "domains": [
      "equalsmoney.com",
      "fairfx.com"
    ]
  }'
Copy
Copied
curl -i -X PUT \
  'https://api.equalsmoney.com/v2/accounts/{accountId}/email-domains' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "domains": [
      "string"
    ]
  }'

Path parameters

Parameter Description
accountId
string
required		 The ID of the account that you want to update the list of approved email domains for.

Allowable values:
An existing accountId (<= 36 characters)

Query parameters

Parameter Description
domains
array of strings
required		 The list of approved email domains. There can be up to 100.

Allowable values:
An array of valid strings (^@?([a-zA-Z0-9]+(-[a-zA-Z0-9]+)*\.)+[a-zA-Z]{2,}$)

Response

If your request is successful, you'll receive a 200 response containing the updated list of approved email domains.

Sample responseResponse structure
Copy
Copied
{
  "count": 2,
  "limit": 100,
  "offset": 0,
  "rows": [
    {
      "id": "a617495e-94f3-4ebb-b398-bb7ce19a70c9",
      "accountId": "F12345",
      "name": "fairfx.com",
      "createdAt": "2023-03-10T11:32:00Z",
      "updatedAt": "2023-03-10T11:32:00Z"
    },
    {
      "id": "8e214819-5c83-429f-a976-eb127a0a8a88",
      "accountId": "F12345",
      "name": "equalsmoney.com",
      "createdAt": "2023-01-30T08:30:00Z",
      "updatedAt": "2023-01-30T08:30:00Z"
    }
  ]
}
Copy
Copied
{
  "count": integer,
  "limit": integer,
  "offset": integer,
  "rows": [
    {
      "id": "string",
      "accountId": "string",
      "name": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}

For more detailed information about this request and its response, see the API reference.

List approved email domains

Get/v2/accounts/{accountId}/email-domains

Request

Use this request to retrieve a list of approved email domains associated with a given account. You'll only be able to create people if their email address contains one of the domains returned in the response.

Sample requestRequest structure
Copy
Copied
curl -i -X GET \
  'https://api.equalsmoney.com/v2/accounts/F12345/email-domains' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
Copy
Copied
curl -i -X GET \
  'https://api.equalsmoney.com/v2/accounts/{accountId}/email-domains' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE'

Path parameters

Parameter Description
accountId
string
required		 The ID of the account that you want to retrieve a list of approved email domains for.

Allowable values:
An existing accountId (<= 36 characters)

Query parameters

Parameter Description
limit
integer		 The maximum number of items to return. For example, limit=25. By default, this is set to 100.

Allowable values:
[ 1 .. 100000 ]
offset
integer		 The number of items to skip before returning the results. For example, offset=200. By default, this is set to 0.

Allowable values:
A valid integer

Response

If your request is successful, you'll receive a 200 response containing a list of approved email domains.

Sample responseResponse structure
Copy
Copied
{
  "count": 1,
  "limit": 100,
  "offset": 0,
  "rows": [
    {
      "id": "8e214819-5c83-429f-a976-eb127a0a8a88",
      "accountId": "F12345",
      "name": "equalsmoney.com",
      "createdAt": "2023-01-30T08:30:00Z",
      "updatedAt": "2023-01-30T08:30:00Z"
    }
  ]
}
Copy
Copied
{
  "count": integer,
  "limit": integer,
  "offset": integer,
  "rows": [
    {
      "id": "string",
      "accountId": "string",
      "name": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}

For more detailed information about this request and its response, see the API reference.