documentation

canonical_email_blocks API methods

Block certain email addresses by their hash.

Last modified Sun Dec 18, 2022
Edit this page

List all canonical email blocks 

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
required 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 /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

Headers
Authorization
required 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 

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
required Provide this header with Bearer <user token> to gain authorized access to this API method.
Form data parameters
email
required 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 

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
required Provide this header with Bearer <user token> to gain authorized access to this API method.
Form data parameters
email
required 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 /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

Headers
Authorization
required 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

app/controllers/api/v1/admin/canonical_email_blocks_controller.rb