Import API Methods

Owned by Pratik Upadhyay
Last updated: Oct 09, 2024 by Stepin\ Shashin Petel
10 min read

Table of Contents:


(info) Note: Notice that in each API call you must provide the List ID that you are working on, otherwise the default List ID will be used. 

Methods Summary

GET /api/import/<Import ID>

Description 

This method returns detailed info for a provided Import ID.

Response Example

GET URL: https://api.ongage.net/<list_id>/api/import/1112223334

{
  "metadata": {
    "error": false
  },
  "payload": {
    "id": 83513,
    "account_id": "60306",
    "list_id": 1234,
    "type": "import",
    "action": "add",
    "name": "filename.csv",
    "file": "4564ef337b1ae36e",
    "imported_by": "1035",
    "is_override": false,
    "save_report": true,
    "send_welcome_message": false,
    "send_email_notification": "0",
    "csv_delimiter": ",",
    "encoding": "UTF-8",
    "progress": "0",
    "size": "0",
    "total": "10",
    "success": "8",
    "failed": "0",
    "duplicate": "2",
    "existing": "0",
    "not_existing": "0",
    "incomplete": "0",
    "invalid": "0",
    "status": 40003,
    "status_desc": "Complete",
    "created": 1461079510,
    "modified": 1461079510,
    "deleted": "0"
  }
}

Error Codes

  • 403 - Permission error
  • 404 - Unauthorized / Import not found

Import Statuses 

"40001": "Queued"
"40010": "Validating"
"40002": "Processing"
"40003": "Completed"
"40004": "Updating list stats"
"90001": "Error"
"90008": "Invalid"
(info)  Any status >= 90000 are final statuses of errors.

GET /api/import

Description 

This method returns a collection of all import details for a given list in the response.

{
   "metadata":{
      "error":false
   },
   "payload":{
      "id":"1541564936",
      "action":"remove",
      "name":"td_inactive_removal_export_4.csv",
      "file":"62b63a53c20cc",
      "file_url":null,
      "imported_by":"17377",
      "is_override":"0",
      "send_welcome_message":"0",
      "send_email_notification":"0",
      "csv_delimiter":",",
      "encoding":"UTF-8",
      "ignore_empty":"0",
      "overwrite_only_nulls":"0",
      "fields":"{\"email\":{\"name\":\"email\",\"type\":\"email\"}}",
      "progress":"46",
      "file_size_bytes":"0",
      "total":"10000000",
      "success":"4097000",
      "failed":"0",
      "duplicate":"0",
      "existing":"0",
      "not_existing":"0",
      "incomplete":"0",
      "invalid":"0",
      "status":"40002",
      "status_info":"",
      "remaining":"",
      "import_process_start_time":"1656110930",
      "import_process_end_time":"0",
      "account_id":"7994",
      "list_id":"50423",
      "created":"1656109652",
      "modified":"1656504791",
      "deleted":"0",
      "can_be_aborted":"1",
      "type":"sending",
      "status_desc":"Processing (46%)"
   }
}

POST /api/import

Description 

This method is used to create an import.

Request

list_id

Optional number - The list id to which the import should be saved under. Default - Default list ID

file_url

Required string - Full url to the CSV/TXT file, or ZIP that contain only 1 CSV/TXT file

csv_delimiter

Required string - Comma (,), Pipe (|), Tab (t) or Semi colon separated (;). Default: Comma (,)

encoding

Optional string - Default: UTF-8

overwrite

Optional boolean - Overwrite existing contact. Default: False

ignore_empty

Optional boolean - Do not overwrite with null values. Default: False

overwrite_only_nulls

Optional boolean - Overwrite only null value fields. Default: False

send_welcome_message

Optional boolean - Send welcome email/SMS to new contacts in this import (Default: False)

fields

Optional json - Default: All fields in current list

import_action

Optional string - Import action:

remove – hard delete for all list types

unsubscribe – unsubscribes (only for sending list type)

resubscribe – revives soft delete and unsubscribe (only for sending list type)

add – adds a new contact(default)

bounce - Marks contacts as Hard bounce

complaint - Marks contacts as complaint

import_type

Optional string - Indicate the type of list you are importing into. Values can be:

sending (Default)

suppression

send_email_notification

Optional string - In order to receive email notification for an import, set the value to true

Request Example - Sending List Import

POST URL: https://api.ongage.net/<list_id>/api/import

{
 "list_id": 1234,
 "file_url": "http://www.yourdomain.com/filename.csv",
 "csv_delimiter": ",",
 "overwrite": true,
 "ignore_empty": true,
 "send_welcome_message": false
 }

Request Example - Suppression list import

POST URL: https://api.ongage.net/<list_id>/api/import

{
"list_id": 1234, //Suppression List ID
"file_url": "http://www.yourdomain.com/filename.csv",
"csv_delimiter": ",",
"import_type" : "suppression",
"import_action" : "add"
}

Response Example

{
  "metadata": {
    "error": false
  },
  "payload": {
    "id": 83513,
  }
}

Error Codes

  • 403 - Permission error
  • 500 - Validation error

Password Protect Import File Feature

  • You can password protect the the file you want to import, by zipping it up into a zip file, and setting a password on that zip file.
  • In order for Ongage to then be able to open that file, go to the Account General Settings Page, and enter there the password needed to open the zip file.

Additional Security Measures Beyond Password Protection

The API import call requires indicating a URL to the import file. You can secure that URL in the following manner:

  • Place the file just prior to the import and delete the file right after the import.
  • On the client's web servers (regardless of which web server) there is always an accesslog. If the file is deleted from the server after Ongage downloaded it + if the access log doesn't show any other download other than Ongage, it means the data is safe.
  • Disabling directory indexing.
  • Renaming the import files to a random and long string will also help protecting against people finding the URL as long as directory indexing is disabled.
  • You can make the directory accessible only to your IPs and Ongage's IPs. Ask Ongage support for how to obtain a list of Ongage IPs.
  • Finally, as an additional security measure you can use https instead of http.

How to Import a file from an S3 bucket

Prerequisites

  • You have AWS account.
  • You have an S3 bucket (With the name ‘my_company_name_ongage_imports’ for example).

Background

In order to initiate an import via Ongage API, you will need to provide a URL to a file that can be downloaded via the API.

If your requirement is to import a file that resides in an S3 bucket, you will need to generate a Pre-signed URL and include the generated URL in the “file_url” field in the Import API request payload as mentioned above under POST API/Import end point.

(warning) Note: In addition to setting up S3 bucket, the initial one time setup will include whitelisting Ongage Server IPs as and if required. It is preferred to schedule scripts that will update the security policy everyday on the newest IPs set of Ongage servers. To know more about Ongage IPs, you can contact Ongage Support.

(warning) Note: Pre-signed URLs that you generate have already a degree of security as they are temporary and expire after a specific period (e.g. 1 hour). As mentioned additional security measures can be achieved by whitelisting the required IPs of Ongage servers.

Step by Step walk through

  1. Setup IAM user and a S3 Bucket Policy with GetObject permissions.
  2. Whitelist Ongage servers IPs as required.
    1. In case that the security policy requires you to whitelist specific IPs. Please use the “aws:SourceIp”. You can follow this example for more details.
    2. The list of IP CIDR ranges to whitelist can be found using this bash command line “nslookup -type=TXT outboundips-space-cidr.ongage.net”

  3. The final bucket Policy is expected to look like;

    {
 "Version": "2012-10-17",
 "Id": "S3GetObjectForOngageImportsBucketViaOngageServers",
 "Statement": [
   {
     "Sid": "allow-ongage-server",
     "Effect": "Allow",
     "Principal": "*",
     "Action": "s3:GetObject",
     "Resource": "arn:aws:s3:::my_company_name_ongage_imports/*",
     "Condition": {
       "IpAddress": {
         "aws:SourceIp": [
           "107.170.213.132/32",
           "107.170.213.133/32",
           "107.170.213.134/32",
           "107.170.213.135/32",
           "107.170.213.136/32",
           "107.170.213.137/32",
           "107.170.213.138/32",
           "107.170.213.139/32",
           "107.170.213.140/32",
           "107.21.59.147/32",
           "107.23.10.125/32",
           "107.23.12.93/32",
           "107.23.14.88/32",
           "107.23.177.90/32",
           "107.23.178.47/32",
           "108.161.135.135/32",
           "108.161.135.37/32",
           "178.128.139.133/32",
           "18.200.73.64/26",
           "192.241.212.130/32",
           "198.199.88.38/32",
           "206.189.241.97/32",
           "207.244.103.131/32",
           "207.244.103.201/32",
           "207.244.103.202/32",
           "207.244.104.119/32",
           "207.244.104.120/32",
           "207.244.104.121/32",
           "207.244.104.122/32",
           "207.244.104.201/32",
           "207.244.104.202/32",
           "207.244.68.218/32",
           "209.208.109.152/32",
           "209.208.109.172/32",
           "209.208.78.150/32",
           "23.20.201.102/32",
           "23.21.219.19/32",
           "23.23.212.1/32",
           "34.224.117.198/32",
           "34.225.42.120/32",
           "34.226.5.95/32",
           "34.227.41.239/32",
           "34.231.210.31/32",
           "34.231.44.192/26",
           "34.232.157.165/32",
           "34.245.82.192/26",
           "34.245.82.199/32",
           "34.245.82.204/32",
           "34.245.82.233/32",
           "34.245.82.234/32",
           "34.245.82.236/32",
           "34.245.82.237/32",
           "34.245.82.244/32",
           "34.245.82.246/32",
           "34.245.82.247/32",
           "34.245.82.248/32",
           "35.153.84.250/32",
           "50.19.198.209/32",
           "50.56.240.150/32",
           "52.0.251.22/32",
           "52.0.56.158/32",
           "52.1.57.9/32",
           "52.1.99.254/32",
           "52.201.178.193/32",
           "52.204.236.101/32",
           "52.208.21.200/32",
           "52.21.252.120/32",
           "52.2.154.228/32",
           "52.21.93.98/32",
           "52.5.100.202/32",
           "52.7.119.14/32",
           "54.165.140.21/32",
           "54.173.254.154/32",
           "54.175.238.172/32",
           "54.208.127.76/32",
           "54.208.164.47/32",
           "54.208.99.126/32",
           "54.209.202.108/32",
           "54.209.204.31/32",
           "54.209.205.54/32",
           "54.209.208.240/32",
           "54.209.210.149/32",
           "54.209.213.207/32",
           "54.209.232.207/32",
           "54.209.238.30/32",
           "54.209.247.123/32",
           "54.209.247.137/32",
           "54.209.252.68/32",
           "54.209.253.24/32",
           "54.209.253.50/32",
           "54.236.65.189/32",
           "54.236.73.137/32",
           "54.236.83.142/32",
           "54.86.137.29/32",
           "54.88.127.35/32",
           "5.79.106.181/32",
           "69.28.92.114/32",
           "69.28.92.155/32",
           "69.28.93.182/32",
           "69.28.94.194/32",
           "69.28.94.223/32",
           "69.28.95.55/32",
           "69.28.95.62/32",
           "81.171.19.60/32",
           "95.85.17.120/32"
         ]
       }
     }
   }
 ]
}

  4. As part of the code that makes the HTTP request to Ongage API, add a code to generate an S3 pre-signed URL via credentials of the IAM user that was granted with the Bucket Policy.

    1. Amazon provides SDK to all common languages, here are sample code for several languages:

      1. Java - https://docs.aws.amazon.com/AmazonS3/latest/dev/ShareObjectPreSignedURLJavaSDK.html

      2. PHP - https://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/s3-presigned-url.html

      3. Python - https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/s3-example-presigned-urls.html

      4. .NET - https://docs.aws.amazon.com/AmazonS3/latest/dev/ShareObjectPreSignedURLDotNetSDK.html

  5. Write the code to execute a POST api/import API call.