Import API Methods
Table of Contents:
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" 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,
"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.
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.
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
- Setup IAM user and a S3 Bucket Policy with GetObject permissions.
- Whitelist Ongage servers IPs as required.
- 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.
- The list of IP CIDR ranges to whitelist can be found using this bash command line “nslookup -type=TXT outboundips-space-cidr.ongage.net”
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" ] } } } ] }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.
Amazon provides SDK to all common languages, here are sample code for several languages:
Java - https://docs.aws.amazon.com/AmazonS3/latest/dev/ShareObjectPreSignedURLJavaSDK.html
PHP - https://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/s3-presigned-url.html
Python - https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/s3-example-presigned-urls.html
.NET - https://docs.aws.amazon.com/AmazonS3/latest/dev/ShareObjectPreSignedURLDotNetSDK.html
Write the code to execute a POST api/import API call.