---
title: "Update sync job source"
method: POST
path: "/api/v1/edit/syncjob_source"
tags: ["Sync jobs"]
---

# Update sync job source

`POST /api/v1/edit/syncjob_source`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/v1/edit/syncjob_source`
- Auth: API key in header `X-API-Key`

Update one or more sync sources (creator, admins, and domain admins for sources created by mailboxes of their domains). Fields not provided are left unchanged. All checks run before anything is written; a rejected edit changes nothing. Requires the `syncjobs` ACL.

## Request body

- object
  - `attr` object
    - `name` string: source name, max. 100 characters, unique per creator
    - `description` string: free text shown in the UI, max. 255 characters
    - `host` string: remote IMAP host (hostname or IP, max. 253 characters). `host1` is accepted as an alias. Host, port and enc are only validated when they change (migrated legacy values stay editable).
    - `port` integer: remote IMAP port (1-65535). `port1` is accepted as an alias.
    - `enc` 'TLS' | 'SSL' | 'PLAIN': TLS (STARTTLS) / SSL / PLAIN. `enc1` is accepted as an alias.
    - `verify_cert` 0 | 1: 1 = check the server certificate (SSL and STARTTLS, default), 0 = do not check it (self-signed, expired or not matching the host). Turning the check off needs access to all sync jobs of the source, like changing the server.
    - `auth_type` 'PLAIN' | 'LOGIN' | 'CRAM-MD5' | 'XOAUTH2': authentication mechanism; PLAIN/LOGIN/CRAM-MD5 use the per-job password, XOAUTH2 uses OAuth2 tokens. XOAUTH2 sources can only be created and edited by admins and domain admins (`access_denied` for users); users can use XOAUTH2 sources visible to them in their sync jobs.
    - `oauth_flow` 'client_credentials' | 'authorization_code': XOAUTH2 grant type (default client_credentials). client_credentials sources are always private to their creator (scope is forced to `user` without targets).
    - `oauth_authorize_endpoint` string: authorize URL, required for authorization_code. Must be an https:// URL without credentials and with a valid hostname
    - `oauth_token_endpoint` string: token URL, required for XOAUTH2. Must be an https:// URL without credentials and with a valid hostname
    - `oauth_userinfo_endpoint` string: optional identity endpoint for authorization_code (used when the token response has no usable id_token). Must be an https:// URL without credentials and with a valid hostname
    - `oauth_client_id` string: OAuth2 client id, required for XOAUTH2
    - `oauth_client_secret` string: OAuth2 client secret; empty keeps the stored one. Changing auth_type, oauth_flow, oauth_token_endpoint, oauth_client_id, host, port or enc drops the cached source token and all per-user tokens of the source (users have to sign in again).
    - `oauth_scope` string: OAuth2 scope, required for XOAUTH2
    - `oauth_extra_params` union: optional extra token request parameters: a JSON object with scalar values, sent either as object or as JSON string (empty = none). They never override the grant fields.
      - object
      - string
    - `scope` 'all' | 'domain' | 'user': visibility: `all` (admins only), `domain` (needs `domains`) or `user` (listed `users`; no targets = private to the creator). Users always create private sources. Targets are only rewritten when `scope` is sent.
    - `domains` string[]: target domains when scope is domain
    - `users` string[]: target mailboxes when scope is user
    - `active` boolean: enables or disables the source
  - `items` string[]: list of source ids to update

## Response `200`

OK

- object
  - `log` unknown[]: contains request object (secrets are masked as "*")
    - unknown
  - `msg` unknown[]
    - unknown
  - `type` 'success' | 'danger' | 'error'

## Other responses

- `401`: Unauthorized

## Changes

- **2026-11-03** `bc8a5589ddad`: 1 info
  - added the new optional request property `attr/verify_cert`
- **2026-10-22** `cf82ac1f801a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/mailcow/apis/mailcow-api/changes/api/v1/edit/syncjob_source/post.md)

---

[API](https://skmtc.dev/mailcow/apis/mailcow-api.md) - [All operations](https://skmtc.dev/mailcow/apis/mailcow-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mailcow/apis/mailcow-api/revisions/bc8a5589ddad?raw)