damex.cloudflare.cloudflare_email_routing_rule module – Ensure Cloudflare email routing rule

Note

This module is part of the damex.cloudflare collection (version 1.2.3).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install damex.cloudflare.

To use it in a playbook, specify: damex.cloudflare.cloudflare_email_routing_rule.

Synopsis

Parameters

Parameter

Comments

account_api_key

string

Cloudflare account API key.

Required together with account_email if api_token is not provided.

account_email

string

Cloudflare account email.

Required together with account_api_key if api_token is not provided.

actions

list / elements=dictionary

Actions to take on matched email.

type

string / required

Action type.

Choices:

  • "drop"

  • "forward"

  • "worker"

value

list / elements=string

Action destination addresses.

Required when type is forward or worker.

api_token

string

Cloudflare API token.

Required if account_email and account_api_key are not provided.

Can be specified in CLOUDFLARE_TOKEN environment variable.

enabled

boolean

Rule enabled state.

Choices:

  • false

  • true ← (default)

matchers

list / elements=dictionary

Matching patterns for incoming email.

field

string

Matcher field.

Required when type is literal.

Choices:

  • "to"

type

string / required

Matcher type.

Choices:

  • "all"

  • "literal"

value

string

Matcher value.

Required when type is literal.

name

string / required

Rule name.

priority

integer

Rule execution priority.

Lower values execute first.

state

string

Rule state.

Choices:

  • "absent"

  • "present" ← (default)

zone_id

string

Zone identifier.

Required if zone_name is not provided.

zone_name

string

Zone domain name.

Required if zone_id is not provided.

Resolved to zone identifier via the Cloudflare API.

Attributes

Attribute

Support

Description

check_mode

Support: full

Supports check mode.

diff_mode

Support: full

Supports diff mode.

Examples

- name: Ensure catch-all forwarding rule
  damex.cloudflare.cloudflare_email_routing_rule:
    name: catch-all
    zone_name: example.com
    api_token: "{{ cloudflare_api_token }}"
    matchers:
      - type: all
    actions:
      - type: forward
        value:
          - [email protected]

- name: Ensure specific address forwarding rule
  damex.cloudflare.cloudflare_email_routing_rule:
    name: admin forwarding
    zone_name: example.com
    api_token: "{{ cloudflare_api_token }}"
    matchers:
      - type: literal
        field: to
        value: [email protected]
    actions:
      - type: forward
        value:
          - [email protected]

- name: Ensure drop rule
  damex.cloudflare.cloudflare_email_routing_rule:
    name: drop spam
    zone_name: example.com
    api_token: "{{ cloudflare_api_token }}"
    matchers:
      - type: literal
        field: to
        value: [email protected]
    actions:
      - type: drop

- name: Ensure rule is absent
  damex.cloudflare.cloudflare_email_routing_rule:
    name: old-rule
    zone_name: example.com
    api_token: "{{ cloudflare_api_token }}"
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

rule

dictionary

Routing rule object from the Cloudflare API.

Returned: when state is present

actions

list / elements=string

Actions to take on matched email.

Returned: success

enabled

boolean

Rule enabled state.

Returned: success

id

string

Rule identifier.

Returned: success

matchers

list / elements=string

Matching patterns.

Returned: success

name

string

Rule name.

Returned: success

priority

integer

Rule execution priority.

Returned: success

Authors

  • Roman Kuzmitskii (@damex)