SFTP

Import through an SFTP account

• Imports are assigned to a UID
• For a successful import, define the data structure in the file and prepare an additional file that maps the structure
• [name].csv and [name].import must have matching names
• Encode .csv and .import files as UTF-8 without a BOM
• Files must not contain the x00 (Null) character

Upload two files through SFTP to /in/import:

• exemple.csv
• exemple.import

You can choose any filename, but both files must share the same base name.

The CSV file should contain the data, email addresses and properties to import. The first row must contain headers/field names.

The IMPORT file should contain the import settings in JSON format. An example structure is shown below:

Example import file

{
  "import": true,
  "system": "sare",
  "group": 45,
  "overwrite": 2,
  "status": 8,
  "fields": {
    "map": {
      "email": "email",
      "cechaNaglowek": "cecha7",
      "foreignKey": "cecha6"
    },
    "foreign_key": "cecha6"
  },
  "csv": {
    "delimiter": ";"
  },
  "duplicates_handling": "skip",
  "checkSpamtrap": false,
  "add_blocked_addresses_to_group": false,
  "sarescript": {
    "before": "<!--sare sare_group_clear(45); sare-->"
  }
}

Import parameters

• import: true / false
  • Enabled / disabled
• system: sare
  • The system to which the import applies
• group: int
  • Group as an int (defaults to 0)
• overwrite:
  • Address overwrite behavior (defaults to 4)
  • Values:
    • 0: Do not import
    • 1: Overwrite status only
    • 2: Overwrite imported data only
    • 3: Overwrite all data (clear history)
    • 4: Overwrite imported data only, including a type change
    • 5: Overwrite imported data and clear properties not included in the import
• status:
  • Status assigned to imported addresses (defaults to 8)
  • Values:
    • 2: Manually unsubscribed
    • 3: Unsubscribed
    • 4: Requested unsubscribe
    • 5: Subscribed, not verified
    • 6: Subscribed, not confirmed
    • 7: Blocked address
    • 8: Subscribed and confirmed
• mail_type:
  • Email format assigned to addresses during import (defaults to text,HTML)
  • Values:
    • text,HTML
    • text

Field mapping

• fields.map:
  • Maps address properties from the first row of the data file to properties defined in SARE
• fields.ignore:
  • Array of data file field names to ignore during import
• fields.foreign_key:
  • Foreign key property name. It must also appear in fields.map or in the import file header. The name must match the property name in the system. This option requires configuration by IT

CSV

• csv.delimiter:
  • Character separating properties in the address file (defaults to ;)
• csv.enclosure:
  • Character marking the start and end of a string (defaults to ")
• csv.escape:
  • Escape character (defaults to \\)

Other parameters

• autodelete:
  • 1 deletes files from the SFTP server after import. 0 leaves the files on the server.
• encrypted:
  • true tells the importer to look for an encrypted import file. false imports an unencrypted file.
• sarescript.before:
  • SAREscript executed before import, e.g. clearing properties, moving addresses to another group or clearing groups
• sarescript.after:
  • SAREscript executed after import, e.g. populating properties, assigning a group or sending a newsletter
• account_id:
  • ID of the account into which data is imported. This parameter is optional when there is only one account. Otherwise, it is assigned in sequence to subsequent accounts enabled for import.
• duplicates_handling:
  • When importing with a foreign key, determines what to do with imported data matching more than one address in the SARE database:
    • default: import all
    • Any other value: skip
  • Defaults to default
• checkSpamtrap:
  • Whether to skip spam traps during import (defaults to false)
• add_blocked_addresses_to_group:
  • Whether to add blocked addresses to the group during import (defaults to false)

Consents

• consent.import:
  • Whether to update the consent information area (required)
• consent.name:
  • Name of the consent information area (required)
• consent.status:
  • Area status (required)
  • Values:
    • 1: No information
    • 2: Yes
    • 3: No

Imports run every 5 minutes. Imported files are moved to the done subdirectory.

File encryption

Encrypting import files

1. A GPG key pair is created.
2. The customer encrypts import files (.csv) using the supplied public key.
3. The customer uploads the encrypted file to their Digitree SFTP account together with a configuration file.
   • Among other settings, the configuration file indicates whether the import file is encrypted:

     "encrypted": true/false

4. Digitree decrypts the received file with the private key.

Encrypting export files

1. The customer creates a GPG key pair and provides Digitree with the public key.
2. Digitree encrypts export files using the supplied public key.
3. Digitree places the encrypted files on the Digitree SFTP server.
4. The customer downloads the file from the Digitree SFTP server.
5. The customer decrypts the downloaded file using the private key.

Exchanging public keys for imports and exports

1. Keys are valid for one year.
2. Each key is sent to the other party in a password-protected archive.
   • The archive password must be communicated through a different channel from the archive itself, e.g. SMS.
3. Digitree requests a key exchange at least 3 weeks before the key expires.
4. Each party provides the required public key to the other party at least 2 weeks before expiry.

Notes

• Only .csv files can be encrypted