MAmailcow
Sync jobs

Create sync job source

Changed on

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.

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)
  • Auth
    API key in header X-API-Key

Request body

namestring

source name, max. 100 characters, unique per creator

descriptionstring

free text shown in the UI, max. 255 characters

hoststring

remote IMAP host (hostname or IP, max. 253 characters). host1 is accepted as an alias.

portinteger

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_cert0 | 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_endpointstring

authorize URL, required for authorization_code. Must be an https:// URL without credentials and with a valid hostname

oauth_token_endpointstring

token URL, required for XOAUTH2. Must be an https:// URL without credentials and with a valid hostname

oauth_userinfo_endpointstring

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_idstring

OAuth2 client id, required for XOAUTH2

oauth_client_secretstring

OAuth2 client secret, required for XOAUTH2. Never returned by GET.

oauth_scopestring

OAuth2 scope, required for XOAUTH2

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.

domainsstring[]

target domains when scope is domain

usersstring[]

target mailboxes when scope is user

activeboolean

enables or disables the source

Example request

{
  "name": "Example import",
  "description": "",
  "host": "imap.example.org",
  "port": "993",
  "enc": "SSL",
  "auth_type": "PLAIN",
  "active": "1",
  "scope": "domain",
  "domains": [
    "example.org"
  ]
}

Response

OK

type'success' | 'danger' | 'error'

Changes