MAmailcow
Sync jobs

Create sync job

Changed on

Create a sync job for a local mailbox. Connection data (host, port, encryption, authentication) comes from the sync source referenced by source_id. Requires the syncjobs ACL (user ACL for mailbox users, domain admin ACL for domain admins).

post/api/v1/add/syncjob

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

usernamestring

local mailcow mailbox (destination, user2); users always create jobs for their own mailbox

source_idinteger

id of a sync source visible to the caller (GET /api/v1/get/syncjob_source/all).

user1string

remote username at the source. For XOAUTH2 authorization_code sources a token for (source_id, local mailbox, user1) must exist, i.e. the mailbox owner must have signed in via /syncjob-oauth first (imapsync_source_oauth_connect_required otherwise).

password1string

remote password, required unless the source uses XOAUTH2 (ignored then)

mins_intervalnumber

sync interval in minutes (1-43800)

subfolder2string

sync into subfolder on destination (empty = do not use subfolder)

maxagenumber

only sync messages up to this age in days (0 = ignore age)

maxbytespersecondnumber

per-job bandwidth limit in bytes/s (0 = unlimited, capped by the global limit)

timeout1number

timeout for connection to remote host

timeout2number

timeout for connection to local host

excludestring

exclude objects (regex)

delete2duplicatesboolean

delete duplicates on destination (--delete2duplicates)

delete1boolean

delete from source when completed (--delete1)

delete2boolean

delete messages on destination that are not on source (--delete2)

automapboolean

try to automap folders ("Sent items", "Sent" => "Sent" etc.) (--automap)

skipcrossduplicatesboolean

skip duplicate messages across folders (first come, first serve) (--skipcrossduplicates)

subscribeallboolean

subscribe all folders (--subscribeall)

dryboolean

dry run, nothing is changed (--dry)

activeboolean

enables or disables the sync job

host1string

Removed. Host, port, encryption and authentication now come from the sync source (source_id, see /api/v1/add/syncjob_source). The attribute is ignored.

port1string

Removed. Host, port, encryption and authentication now come from the sync source (source_id, see /api/v1/add/syncjob_source). The attribute is ignored.

enc1string

Removed. Host, port, encryption and authentication now come from the sync source (source_id, see /api/v1/add/syncjob_source). The attribute is ignored.

authmech1string

Removed. Host, port, encryption and authentication now come from the sync source (source_id, see /api/v1/add/syncjob_source). The attribute is ignored.

Example request

{
  "username": "lisa@mailcow.tld",
  "source_id": "3",
  "user1": "demo@remote.tld",
  "password1": "supersecretpw",
  "mins_interval": "20",
  "subfolder2": "/SyncIntoSubfolder",
  "maxage": "0",
  "maxbytespersecond": "0",
  "timeout1": "600",
  "timeout2": "600",
  "exclude": "(?i)spam|(?i)junk",
  "custom_params": [
    {
      "o": "folder",
      "v": "INBOX"
    },
    {
      "o": "syncinternaldates",
      "v": ""
    }
  ],
  "delete2duplicates": "1",
  "delete1": "0",
  "delete2": "0",
  "automap": "1",
  "skipcrossduplicates": "0",
  "subscribeall": "1",
  "dry": "0",
  "active": "1"
}

Response

OK

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

Changes

  • cf82ac1f801aRevision changes
    • breaking

      the request property type changed from string to array

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      request property deprecated

    • info

      request property deprecated

    • info

      request property deprecated

  • 844ea6eb90b8Revision changes
    • info

      added the new optional request property