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

# Create sync job source

`POST /api/v1/add/syncjob_source`

## Request

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

Create a reusable IMAP sync source. A sync job binds to a source by id; the source carries host/port/encryption and either static credentials (PLAIN/LOGIN/CRAM-MD5 — the password is supplied per job) or an OAuth2 configuration (XOAUTH2). Requires the `syncjobs` ACL. Validation errors are returned as translated `danger` messages, nothing is written then.

## Request body

- 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.
  - `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).
  - `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, required for XOAUTH2. Never returned by GET.
  - `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.
  - `domains` string[]: target domains when scope is domain
  - `users` string[]: target mailboxes when scope is user
  - `active` boolean: enables or disables the source

## 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 `verify_cert`
- **2026-10-22** `cf82ac1f801a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/mailcow/apis/mailcow-api/changes/api/v1/add/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)