|
| 1 | +--- |
| 2 | +title: Allowed email domains |
| 3 | +description: Let people with a verified company email address find and join your team without an invitation |
| 4 | +--- |
| 5 | + |
| 6 | +An allowed email domain offers your team to anyone whose verified email address is at that domain. Spacefast never adds anyone automatically. A person becomes a member only when they press **Join**. |
| 7 | + |
| 8 | +Only owners and admins can add or remove domains. An OAuth token needs the `teams:members.write` scope, including to list them. |
| 9 | + |
| 10 | +## Add a domain |
| 11 | + |
| 12 | +1. Open the team and go to **Members**. |
| 13 | +2. Press **Join Link**. The **Let Teammates Join** dialog opens. |
| 14 | +3. Type the domain, for example `example.com`, in **Company email domain**. |
| 15 | +4. Press **Add Domain**. |
| 16 | + |
| 17 | +Over HTTP, send [`createTeamAutoEnrollEntry`](/api/reference/teams/createteamautoenrollentry): |
| 18 | + |
| 19 | +```bash |
| 20 | +curl "https://api.spacefast.com/v1/teams/$TEAM_ID/auto-enroll" \ |
| 21 | + -H "Authorization: Bearer $SPACEFAST_API_KEY" \ |
| 22 | + -H "Content-Type: application/json" \ |
| 23 | + -d '{"value":"example.com"}' |
| 24 | +``` |
| 25 | + |
| 26 | +The `201` response holds the entry: `id`, `teamId`, `kind` (always `domain`), `value`, and `createdAt`. Adding a domain the team already has returns the existing entry. [`listTeamAutoEnrollEntries`](/api/reference/teams/listteamautoenrollentries) returns all entries, newest first. |
| 27 | + |
| 28 | +Adding a domain needs a credential that acts for a person. A team API key or OAuth app acts for the person who created it. A key with no person behind it gets `forbidden`. |
| 29 | + |
| 30 | +## Which domains Spacefast accepts |
| 31 | + |
| 32 | +A domain is accepted when all of these are true: |
| 33 | + |
| 34 | +- **A current member already uses it.** At least one member of this team must have a verified email address at exactly that domain. A subdomain does not count. |
| 35 | +- **It is a domain, not an address.** A value with `@` is refused. Invite that person by email instead. |
| 36 | +- **It is a registrable domain.** IP addresses, single labels such as `localhost`, and public suffixes such as `co.uk` are refused. |
| 37 | +- **It is not a shared mailbox provider.** These are refused: `gmail.com`, `googlemail.com`, `outlook.com`, `hotmail.com`, `live.com`, `yahoo.com`, `proton.me`, `protonmail.com`, `icloud.com`, `me.com`, `aol.com`, `mail.com`, `gmx.com`, and `wordpress.com`. |
| 38 | + |
| 39 | +Spacefast stores the canonical form: lowercase ASCII, with international names converted to their `xn--` form. `Bücher.de` becomes `xn--bcher-kva.de`. Matching uses the same form, so either spelling works for people who join. |
| 40 | + |
| 41 | +## What a person sees |
| 42 | + |
| 43 | +A signed-in person with a verified address at the domain sees your team under **Open invites** on the **Teams** page. The row reads **You have an @example.com email**. Their team's Spaces page also shows a **Teams you can join** notice with **View Teams**. |
| 44 | + |
| 45 | +Every verified address on the account counts, including secondary addresses. The account does not need to use that address to sign in. |
| 46 | + |
| 47 | +Pressing **Join** makes them a member with the `member` role. Owners and admins can change the role later on **Members**. Joining needs a signed-in browser session. An API key or an agent cannot join for a person. The API operation is [`joinTeam`](/api/reference/teams/jointeam). |
| 48 | + |
| 49 | +## Seats and billing |
| 50 | + |
| 51 | +A person who joins through a domain takes a seat like any other member. Members on Pro: {{plan-team-members-pro}}. |
| 52 | + |
| 53 | +Personal and Go allow one member, the owner. On those plans, **Join** fails with `team_member_quota_exceeded`, so nobody can join until the team moves to Pro. See [Pricing & Limits](/pricing). |
| 54 | + |
| 55 | +## Remove a domain |
| 56 | + |
| 57 | +In **Join Link**, press **Remove** next to the domain. Confirm with **Remove Domain**. |
| 58 | + |
| 59 | +Over HTTP, send [`deleteTeamAutoEnrollEntry`](/api/reference/teams/deleteteamautoenrollentry) with the entry `id`. It answers `204`. |
| 60 | + |
| 61 | +- **Existing members stay.** Removing a domain changes no membership and no role. |
| 62 | +- **New people need an invitation.** The team stops appearing under their **Open invites**. |
| 63 | + |
| 64 | +To take access away from someone who joined through a domain, remove them on **Members**. See [Teams and members](/teams#change-a-role-or-remove-someone). |
| 65 | + |
| 66 | +A member you remove cannot rejoin through the domain. To bring them back, send an invitation. A member who leaves on their own can rejoin through the domain. |
| 67 | + |
| 68 | +## Errors |
| 69 | + |
| 70 | +| Code | Status | Meaning | |
| 71 | +| --- | --- | --- | |
| 72 | +| `invalid_domain_name` | 422 | The value is not a registrable domain. IP addresses and public suffixes land here | |
| 73 | +| `validation_error` | 422 | `details.reason` says why. `email_not_supported`: the value is an email address. `domain_not_allowed`: the domain is a shared mailbox provider. `domain_not_represented`: no member has a verified address there | |
| 74 | +| `not_found` | 404 | The entry does not exist or belongs to another team | |
| 75 | +| `forbidden` | 403 | Your role cannot manage members, or the credential has no person behind it | |
| 76 | +| `team_member_quota_exceeded` | 409 | A person pressed **Join** while the team was at its member limit | |
0 commit comments