# الإعداد

> ملف YAML الخاص بـ mailctl: مكانه، وكل مفاتيحه، والفحوص التي تجري عند تحميله.

ملف YAML واحد يصف كل النطاقات. تُرفض المفاتيح المجهولة مع اسم الحقل ورقم سطره بدل تجاهلها، فيصير الخطأ المطبعي خطأً واضحًا بدل إعداد لا يفعل شيئًا بصمت.

## أين الملف

يستخدم mailctl أول ما يكون مضبوطًا أو موجودًا من التالي:

1.  `-config <path>`
    
2.  `$MAILCTL_CONFIG`
    
3.  `./mailctl.yaml` في مجلد العمل
    
4.  `$XDG_CONFIG_HOME/mailctl/mailctl.yaml` (أي `~/.config/mailctl/mailctl.yaml` حين لا يكون `XDG_CONFIG_HOME` مضبوطًا)
    

المسار الخاص بالمستخدم هو مكان الإعداد الحقيقي. فهو يُبقي نطاقاتك خارج أي نسخة مستودع قد تنشرها، ويسمح بتشغيل `mailctl` وخادم MCP من أي مجلد. يطبع `mailctl doctor` الملف الذي وجده وسبب اختياره.

## المستوى الأعلى

```yaml
version: 1                          # required, must be 1

cloudflare:
  accountId: ${CLOUDFLARE_ACCOUNT_ID}
  baseUrl: https://api.cloudflare.com/client/v4   # optional
  ttl: 1                            # 1 means automatic

purelymail:
  baseUrl: https://purelymail.com   # optional

domains: [...]
```

يمكن لأي قيمة نصية أن تشير إلى متغير بيئة بـ `${NAME}`. المتغير غير المضبوط خطأ.

## النطاق

```yaml
domains:
  - name: example.com
    zoneName: example.com     # defaults to name; set when the Cloudflare zone differs
    mail: {...}
    mailboxes: [...]
    aliases: [...]
    catchAll: {...}
    deliverability: {...}
```

## mail

```yaml
mail:
  provider: purelymail        # a name, or a list of names
  settings: {...}             # purelymail only
  ms365: {...}                # ms365 only
```

يقبل `provider` اسمًا واحدًا أو قائمة. وينقسم المزوّدون إلى مجموعتين:

الوارد

`purelymail`، `cfrouting`، `ms365`. كل منها ينشر سجلات MX ويملك البريد الوارد. **يمكن للنطاق أن يذكر واحدًا منها على الأكثر**، لأن مزوّدَين يتنافسان على سجل MX نفسه لا يمكن أن يفوزا معًا.

الصادر فقط

`cfsending`. يقترن بأي مزوّد وارد.

المزوّد الذي يوجّه البريد ولا يستضيفه، أي `cfrouting` و`cfsending`، لا يمكن أن تكون له كتلة `mailboxes`. التصريح بها خطأ.

### mail.settings (purelymail)

```yaml
mail:
  provider: purelymail
  settings:
    allowAccountReset: true
    symbolicSubaddressing: false
```

يستحق `symbolicSubaddressing` الفهم قبل أن تختار العناوين. ما دام مفعّلًا، يرفض Purelymail **أي** رمز في اسم المستخدم، لأن `first.last` سيُفهم على أنه المستخدم `first` بالوسم `last`. لذا لا يمكن استخدام `first.last@example.com` إلا حين تكون قيمته `false`، على حساب خسارة عناوين `+tag` في النطاق كله.

### mail.ms365

راجع [Microsoft 365](providers/ms365.html).

## mailboxes

```yaml
mailboxes:
  - address: contact@example.com
    passwordEnv: CONTACT_PASSWORD       # omit to generate one
    displayName: Contact                # ms365 only
    license: BUSINESS_STANDARD          # ms365 only, overrides the domain default
    enablePasswordReset: true           # purelymail only
    enableSearchIndexing: true          # purelymail only
    requireTwoFactorAuthentication: false   # purelymail only
    sendWelcomeEmail: false             # purelymail only
    recovery:                           # purelymail only
      - type: email
        target: recovery@example.net
        description: personal
        allowMfaReset: false
```

تُرفض المفاتيح الخاصة بمزوّد ما على المزوّد الخطأ بدل تجاهلها. فتجاهل `requireTwoFactorAuthentication` سيبدو كمصادقة ثنائية مفروضة لا وجود لها.

## aliases

```yaml
aliases:
  - match: info                     # exact match on the local part
    to: [contact@example.com]
  - match: sales*                   # trailing * matches any local part starting with sales
    to: [contact@example.com]
```

غير متاحة لدى كل المزوّدين. يرفض `ms365` هذه الكتلة، لأن Microsoft Graph يعرض الحقل الأساسي للقراءة فقط.

## catchAll

```yaml
catchAll:
  to: [contact@example.com]
```

حذف `catchAll` كليًا يعني **اترك ما هو موجود كما هو**، لا "احذفه". القراءتان لا تتميزان في YAML، وإحداهما تُضيّع البريد بصمت، فيأخذ mailctl القراءة الآمنة. لإزالة الالتقاط الشامل، أزله لدى المزوّد.

## deliverability

```yaml
deliverability:
  spfIncludes:
    - include:servers.mailgun.org

  dmarc:
    policy: quarantine        # none | quarantine | reject
    subdomainPolicy: reject
    pct: 100                  # omit to default to 100
    rua: mailto:dmarc@example.com

  tlsRpt: mailto:tls-reports@example.com

  bimi:
    logo: https://example.com/logo.svg

  mtaSts:
    mode: testing             # none | testing | enforce
    maxAge: 604800            # optional
    deploy: true              # upload and bind the policy-serving Worker
```

راجع [قابلية التسليم](deliverability.html) لمعرفة عمل كل سجل وترتيب تفعيلها.

مدخلات `spfIncludes` آليات مفردة. بلا مسافات، وبلا محدِّد `all`، وبلا معدِّل `redirect=`: يستنتج mailctl أشد محدِّد بنفسه، ويرفض كل ما قد يتجاوز السجل الذي يبنيه.

## التحقق

يبلّغ التحقق عن كل المشكلات دفعة واحدة بدل التوقف عند أولها، فالإعداد الذي فيه ثلاثة أخطاء يحتاج إلى تشغيل واحد لإصلاحه لا ثلاثة. تذكر الأخطاء النطاق والحقل وما يجب فعله.

الفحوص التي تلتقط أكثر الأخطاء شيوعًا:

-   مزوّد وارد واحد بالضبط لكل نطاق
    
-   لا `mailboxes` على مزوّد لا يستطيع استضافتها
    
-   لا مفتاح خاص بمزوّد على المزوّد الخطأ
    
-   إشارة `${ENV}` إلى متغير غير مضبوط
    
-   مدخل في `spfIncludes` قد يتجاوز محدِّد السجل
    
-   مفتاح مجهول في أي مكان، مع رقم سطره