Remove email patterns

POST /organizations/{organizationId}/contexts/sign-in/{contextId}/access-policies/{policyId}/email-patterns/remove

Permission: Sign In › Access Policies (Write). See API permissions.

Removes up to 500 email patterns, each once. The response has one result per pattern, in the order sent, and all the patterns of the policy after the removal. Repeating the call is safe.

• Case does not matter. A pattern matches the patterns of the policy ignoring case: Alice@Example.com removes alice@example.com. A pattern stored in upper or mixed case is removed too, and a pattern stored in more than one case is removed in every case, with one result and one revoked for all of them.
• A missing pattern is reported, not refused. A pattern the policy does not have gets the outcome NOT_IN_POLICY, and nothing changes for it.
• Access is kept by default. Without revokeAccess, the removal stops future matches only. With revokeAccess set to true, the access the removed addresses hold in the context ends as well.

Request

Parameter	In	Type	Required	Description
organizationId	Path	string	Yes	The Organization ID of the API key. Any other ID returns 404.
contextId	Path	string	Yes	The ID of a Sign-In Context of the Organization. Any other ID returns 404.
policyId	Path	string	Yes	The ID of the access policy, from List access policies. An unknown ID returns 404.
emailPatterns	Body	string[]	Yes	The email addresses or domains to remove. 1 to 500 patterns, each 1 to 254 characters, not blank, each once.
revokeAccess	Body	boolean	No	true to also end the access each removed pattern holds in the context; otherwise false. Default false.

With revokeAccess, each removed pattern is read as one email address, and three things end for that address:

• its active Self-Provisioning by Email logins;
• the active Meeting Host logins that name it as the host;
• the active whitelistings it created.

The pattern is compared with the exact address. A domain pattern such as @example.com matches no single address, so nothing ends for it.

Request example

cURL

curl -X POST "$API_BASE_URL/organizations/$ORGANIZATION_ID/contexts/sign-in/$CONTEXT_ID/access-policies/66f2a1c4e8b0a93d5c1e7f20/email-patterns/remove" \
  -H "Authorization: Bearer $NCP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "emailPatterns": ["Alice@Example.com", "dave@example.com"],
    "revokeAccess": true
  }'

Response

Field	Type	Description
results	object[]	One entry per pattern sent, in the order sent.
results[].emailPattern	string	The pattern as sent, trimmed and in lower case.
results[].outcome	string	REMOVED, or NOT_IN_POLICY when the policy did not have the pattern. New values can be added within v2.
results[].revoked	object or null	What ended for a removed pattern, summed over every case it was stored in. null for NOT_IN_POLICY.
results[].revoked.selfProvisioningLogins	integer	The number of Self-Provisioning by Email logins that were ended.
results[].revoked.meetingHostLogins	integer	The number of Meeting Host logins that were ended.
results[].revoked.whitelistings	integer	The number of whitelistings that were ended.
results[].reason	null	Always null in this operation.
emailPatterns	string[]	All the patterns of the policy after the removal, sorted.

The three counts are 0 unless revokeAccess is true.

Response example

200

{
  "results": [
    {
      "emailPattern": "alice@example.com",
      "outcome": "REMOVED",
      "revoked": { "selfProvisioningLogins": 2, "meetingHostLogins": 0, "whitelistings": 1 },
      "reason": null
    },
    { "emailPattern": "dave@example.com", "outcome": "NOT_IN_POLICY", "revoked": null, "reason": null }
  ],
  "emailPatterns": ["@example.org", "carol@example.com"]
}

In this example the policy did not have dave@example.com, so nothing changed for it.

Errors

Status	errorCode	When
400	VALIDATION_FAILED	The list is empty or has more than 500 patterns, or a pattern is blank or longer than 254 characters. errors names each pattern. Nothing is removed.
400	VALIDATION_FAILED	A pattern is sent twice, in any case: errors names the second one with the code DUPLICATE. Nothing is removed.
404	RESOURCE_NOT_FOUND	The context has no access policy with this ID, organizationId is not the Organization of the API key, or contextId is not one of its Sign-In Contexts.

Errors common to all operations are in Errors.