documentation/content/en/methods/admin/canonical_email_blocks.md

---

title: canonical_email_blocks API methods description: Block certain email addresses by their hash. menu: docs:

name: canonical_email_blocks
parent: methods-admin
identifier: methods-admin-canonical_email_blocks

aliases: [ "/methods/admin/canonical_email_blocks", "/api/methods/admin/canonical_email_blocks",

]

List all canonical email blocks {#get}

GET /api/v1/admin/canonical_email_blocks HTTP/1.1

Returns: Array of Admin::CanonicalEmailBlock\ OAuth: User token + admin:read:canonical_email_blocks\ Permissions: Manage Blocks\ Version history:\ 4.0.0 - added

Request

Headers

Authorization : {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Query parameters

max_id : Internal parameter. Use HTTP Link header for pagination.

since_id : Internal parameter. Use HTTP Link header for pagination.

min_id : Internal parameter. Use HTTP Link header for pagination.

limit : Integer. Maximum number of results to return. Defaults to 100 blocks. Max 200 blocks.

Response

200: OK

[
  {
    "id": "1",
    "canonical_email_hash": "b344e55d11b3fc25d0d53194e0475838bf17e9be67ce3e6469956222d9a34f9c"
  },
  // ...
]

Because CanonicalEmailBlock IDs are generally not exposed via any API responses, you will have to parse the HTTP Link header to load older or newer results. See Paginating through API responses for more information.

Link: <http://mastodon.example/api/v1/admin/canonical_email_blocks?limit=2&max_id=2>; rel="next", <http://mastodon.example/api/v1/admin/canonical_email_blocks?limit=2&since_id=1>; rel="prev"

403: Forbidden

Authorized user is missing a permission, or invalid or missing Authorization header

{
  "error": "This action is not allowed"
}

---

Show a single canonical email block {#get-one}

GET /api/v1/admin/canonical_email_blocks/:id HTTP/1.1

Returns: Admin::CanonicalEmailBlock\ OAuth: User token + admin:read:canonical_email_blocks\ Permissions: Manage Blocks\ Version history:\ 4.0.0 - added

Request

Path parameters

:id : {{}} String. The ID of the Admin::CanonicalEmailBlock in the database.

Headers

Authorization : {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

{
  "id": "1",
  "canonical_email_hash": "b344e55d11b3fc25d0d53194e0475838bf17e9be67ce3e6469956222d9a34f9c"
}

403: Forbidden

Authorized user is missing a permission, or invalid or missing Authorization header

{
  "error": "This action is not allowed"
}

404: Not found

Canonical email block does not exist or was already deleted

{
  "error": "Record not found"
}

---

Test {#test}

POST /api/v1/admin/canonical_email_blocks/test HTTP/1.1

Canoniocalize and hash an email address.

Returns: Array of Admin::CanonicalEmailBlock\ OAuth: User token + admin:read:canonical_email_blocks\ Permissions: Manage Blocks\ Version history:\ 4.0.0 - added

Request

Headers

Authorization : {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Form data parameters

email : {{}} String. The email to canonicalize and hash.

Response

200: OK

All matching canonical email blocks are returned.

[
  {
    "id": "1",
    "canonical_email_hash": "b344e55d11b3fc25d0d53194e0475838bf17e9be67ce3e6469956222d9a34f9c"
  }
]

403: Forbidden

Authorized user is missing a permission, or invalid or missing Authorization header

{
  "error": "This action is not allowed"
}

500: Server error

No email was provided

---

Block a canonical email {#create}

POST /api/v1/admin/canonical_email_blocks HTTP/1.1

Returns: Admin::CanonicalEmailBlock\ OAuth: User token + admin:write:canonical_email_blocks\ Permissions: Manage Blocks\ Version history:\ 4.0.0 - added

Request

Headers

Authorization : {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Form data parameters

email : {{}} String. The email to canonicalize, hash, and block. If this parameter is provided, canonical_email_hash will be ignored.

canonical_email_hash : String. The hash to test against. If email is not provided, this parameter is required.

Response

200: OK

Canonical email has been successfully blocked

{
  "id": "1",
  "canonical_email_hash": "b344e55d11b3fc25d0d53194e0475838bf17e9be67ce3e6469956222d9a34f9c"
}

403: Forbidden

Authorized user is missing a permission, or invalid or missing Authorization header

{
  "error": "This action is not allowed"
}

422: Unprocessable entity

Canonical email hash is already blocked

{
  "error":"Validation failed: Canonical email hash has already been taken"
}

---

Delete a canonical email block {#delete}

DELETE /api/v1/admin/canonical_email_blocks/:id HTTP/1.1

Returns: Admin::CanonicalEmailBlock\ OAuth: User token + admin:write:canonical_email_blocks\ Permissions: Manage Blocks\ Version history:\ 4.0.0 - added

Request

Path parameters

:id : {{}} String. The ID of the Admin::CanonicalEmailBlock in the database.

Headers

Authorization : {{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

Canonical email block successfully deleted.

{}

403: Forbidden

Authorized user is missing a permission, or invalid or missing Authorization header

{
  "error": "This action is not allowed"
}

404: Not found

Canonical email block does not exist or was already deleted

{
  "error": "Record not found"
}

---

See also

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/canonical_email_blocks_controller.rb" caption="app/controllers/api/v1/admin/canonical_email_blocks_controller.rb" >}}