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.
This method returns detailed info for a provided Import ID.
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" } } |
"40001": "Queued"
"40010": "Validating"
"40002": "Processing"
"40003": "Completed"
"40004": "Updating list stats"
"90001": "Error"
"90008": "Invalid"
Any status >= 90000 are final statuses of errors.
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%)" } } |
This method is used to create an import.
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
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 } |
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" } |
{ "metadata": { "error": false }, "payload": { "id": 83513, } } |
The API import call requires indicating a URL to the import file. You can secure that URL in the following manner:
Prerequisites
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
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.