Notification Service API
The Notification Service allows easy integration for getting data about Emails and SMS Notifications.
Authentication and authorization for the NotificationService
will be done with a Base64 encoded
username:password
, passed in through the BASIC HTTP Authorization Header.
General Service Notes
GET
|
Retrieve a single entity or a list of entities. |
RESPONSE
|
In general, fields will only be returned if their value is not null or empty. |
Email Configuration
Test URL:
https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/configure
Live URL:
https://notification.pdc4u.com/NotificationService/api/v1_0/emails/configure
Enable or Disable Email OptOut
A POST
will create or update a ConfigureMail
object.
A GET
will retrieve a ConfigureMail
object for the companyId provided.
ConfigureMail Object
Attribute | Description |
useOptOut
boolean
|
Should the company use the email OptOut logic. |
Email Validate
Test URL:
https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/validate
Live URL:
https://notification.pdc4u.com/NotificationService/api/v1_0/emails/validate
Validate a list of email addresses to check if they have Opted Out or Bounced.
POST
an EmailAddressList
object to see which email addresses have Opted Out or Bounced
If all valid an HttpStatus 200
is returned.
If any/all invalid an HttpStatus 400
is returned.
Any failures will be returned in a
RequestErrorList
object with an error and description for each invalid email address
Request EmailAddressList
Attribute | Description |
emailAddressList
Alphanumeric List75
|
The list of Email Addresses to validate. |
Email Blocked Search
Test URL:
https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/blocked/search
Live URL:
https://notification.pdc4u.com/NotificationService/api/v1_0/emails/blocked/search
POST
EmailBlockedSearchParameters
to this url to get an EmailBlockedList
containing all blocked email addresses that match the search parameters.
Request EmailBlockedSearchParameters
Attribute | Description |
emailAddressList
Alphanumeric List75
|
A list of email addresses to filter the search by. |
startDate
Alphanumeric19
|
Starting date to limit the search by. Format: ISO-8601 (YYYY-MM-DD HH:mm:ss) |
endDate
Alphanumeric19
|
Ending date to limit the search by. Format: ISO-8601 (YYYY-MM-DD HH:mm:ss) |
reasonList
ListN/A
|
Filters results by the listed blocked reason(s). If this value is not included, results will contain emails that have been OPTED_OUT and BOUNCED .Valid values: OPTED_OUT BOUNCED Note: Other values will be ignored. |
recordCount
NumericN/A
|
Limits the number of records returned by the search. Default: 2000 Max: 5000 |
recordStart
NumericN/A
|
Starting index of the returned results. Default: 0 |
Response EmailBlockedList
Attribute | Description |
emailBlockedList
ListN/A
|
A list of EmailBlocked objects.
|
EmailBlocked
Attribute | Description |
companyId
Numeric8
|
The company id associated with the email address that has been blocked. |
emailAddress
Alphanumeric75
|
The email address that has been blocked. |
date
Alphanumeric19
|
The date the email address was blocked. Format: ISO-8601 (YYYY-MM-DD HH:mm:ss) |
reason
Alphanumeric19
|
The reason the email address was blocked. Possible values: OPTED_OUT - A user has opted out of receiving emails from this company idBOUNCED - An email address was unable to be delivered
|
Email Unblock
Test URL:
https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/unblock
Live URL:
https://notification.pdc4u.com/NotificationService/api/v1_0/emails/unblock
Unblock a list of email addresses. This will remove them from the Opted Out and/or Bounced list.
NOTE: This endpoint will ignore invalid email addresses and/or those not blocked.
POST
an EmailAddressList
object to unblock the email addresses.
HttpStatus 200
is returned for a valid request.
HttpStatus 400
is returned for an invalid request. Errors will be provided in a RequestErrorList
object.
Request EmailAddressList
Attribute | Description |
emailAddressList
Alphanumeric List75
|
The list of Email Addresses to unblock. |
SMS Validate
Test URL:
https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/sms/validate/{phoneNumber}
Live URL:
https://notification.pdc4u.com/NotificationService/api/v1_0/sms/validate/{phoneNumber}
Request to validate a Phone Number. This includes checking if the Phone Number has Opted Out from receiving SMS.
GET
to see if the phone number has Opted Out
If valid an HttpStatus 200
is returned.
If invalid an HttpStatus 400
is returned.
A failure will be returned in a RequestErrorList
object with the error(s) and description for the invalid phone number
REST Fault
RequestErrorList
Attribute | Description |
requestErrorList
ListN/A
|
A list of RequestError objects containing errors.
Constraint(s): Only returned when errors occur.
|
RequestError
Attribute | Description |
code
Alpha3
|
The code for the validation error. |
errorCode
Numeric5
|
The error code of the validation error. |
description
AlphanumericN/A
|
The description of the validation error. |
retriable
Boolean5
|
Boolean to specify if the same request can be retried. This indicates a temporary failure. |
apiFieldNameList
ListN/A
|
List of ApiFieldName with the specified RequestError
|
ApiFieldName
Attribute | Description |
apiFieldName
Alphanumeric
|
The name of the Api Field. |
apiFieldValue
Alphanumeric
|
The value of the Api Field. When the Api Field is a list, this will show the specific list value which failed. |
Sample Code
This section offers some client implementation examples in different languages. Keep in mind, these are only minimalistic examples used to demonstrate the Notification Service REST API and are not meant for production use.
Result Status Codes
Expected Http Status codes
Status '200':
Description = 'Success.'
Status: '400':
Description = 'Malformed request. The request is either incorrectly formatted, or there are validation errors.'
Status '401':
Description = 'Invalid credentials.'
Status '403':
Description = 'Service not activated.'
Status '404':
Description = 'The requested resource was not found.'
Status '500':
Description = 'An internal error has occurred.'
All requests will return a status code. For example, in the case of status code 400
, check for a
requestErrorList
in the response, containing information on validation failure.
Sample Email Validate
<?php
$url = 'https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/validate';
$data = [
'emailAddressList' => [
'email1@example.com',
'email2@example.com'
]
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_POST, 1);
$data = json_encode($data, JSON_UNESCAPED_SLASHES);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Content-Length: ' . strlen($data),
]);
curl_setopt($curl, CURLOPT_USERPWD, "someSecretUsername:someSecretPassword");
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($curl, CURLOPT_TIMEOUT, 30);
$result = curl_exec($curl);
$statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
// View response
print_r(json_decode($result, true));
if($statusCode == '200') {
echo $result;
}
else {
echo "Error #:" . $statusCode;
}
curl_close($curl);
#!/usr/bin/perl
use LWP::UserAgent;
use HTTP::Request;
use JSON::XS;
use IO::Socket::SSL qw(debug3); # verbose for troubleshooting
eval {
my $data = {
'emailAddressList' => {
'email1@example.com',
'email2@example.com'
}
}
$data = JSON::XS->new->utf8->encode ($data);
my $url = 'https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/validate';
my $req = HTTP::Request->new( 'POST', $url );
$req->authorization_basic( 'SomeSecretUsername', 'SomeSecretPassword' );
$req->content_type('application/json');
$req->content_length( length($data) );
$req->content( $data );
my $lwp = LWP::UserAgent->new;
$lwp->timeout(30);
my $response = $lwp->request( $req );
if ( $response->is_success ) {
print "Success: " . $response->decoded_content;
}
else {
die $response->status_line . ": " . $response->decoded_content;
}
};
if ( $@ ) {
print "Error: $@\n";
}
#!/usr/bin/ruby
require 'curl'
require 'curb'
require 'json'
begin
data = {
'emailAddressList' => {
'email1@example.com',
'email2@example.com'
}
}
c = Curl::Easy.new
c.url = 'https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/validate'
c.http_auth_types = :basic
c.username = 'SomeSecretUsername'
c.password = 'SomeSecretPassword'
c.connect_timeout = 5
c.timeout = 30
c.verbose = true
headers={}
headers['Content-Type'] = 'application/json'
headers['Content-Length'] = data.to_json.length
payload = data.to_json
c.headers = headers
c.http_post(payload)
puts JSON.parse c.body_str
if c.response_code == 200 then
puts "Success " + c.status
else
puts "Error " + c.status
end
rescue
puts "Caught: #$!\n"
end
POST
an EmailAddressList
object to see which email addresses have Opted Out or Bounced
Test URL:
https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/validate
Live URL:
https://notification.pdc4u.com/NotificationService/api/v1_0/emails/validate
Sample EmailBlocked Search
<?php
$url = 'https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/blocked/search';
$data = [
'emailAddressList': [
'email1@example.com',
'email2@example.com'
],
'startDate': '2021-08-01 00:00:00',
'endDate': '2021-08-09 23:59:59',
'reasonList': [
'OPTED_OUT'
],
'recordCount': 5000,
'recordStart': 0
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_POST, 1);
$data = json_encode($data, JSON_UNESCAPED_SLASHES);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Content-Length: ' . strlen($data),
]);
curl_setopt($curl, CURLOPT_USERPWD, "someSecretUsername:someSecretPassword");
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($curl, CURLOPT_TIMEOUT, 30);
$result = curl_exec($curl);
$statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
// View response
print_r(json_decode($result, true));
if($statusCode == '200') {
echo $result;
}
else {
echo "Error #:" . $statusCode;
}
curl_close($curl);
#!/usr/bin/perl
use LWP::UserAgent;
use HTTP::Request;
use JSON::XS;
use IO::Socket::SSL qw(debug3); # verbose for troubleshooting
eval {
my $data = {
'emailAddressList': {
'email1@example.com',
'email2@example.com'
},
'startDate': '2021-08-01 00:00:00',
'endDate': '2021-08-09 23:59:59',
'reasonList': {
'OPTED_OUT'
},
'recordCount': 5000,
'recordStart': 0
}
$data = JSON::XS->new->utf8->encode ($data);
my $url = 'https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/blocked/search';
my $req = HTTP::Request->new( 'POST', $url );
$req->authorization_basic( 'SomeSecretUsername', 'SomeSecretPassword' );
$req->content_type('application/json');
$req->content_length( length($data) );
$req->content( $data );
my $lwp = LWP::UserAgent->new;
$lwp->timeout(30);
my $response = $lwp->request( $req );
if ( $response->is_success ) {
print "Success: " . $response->decoded_content;
}
else {
die $response->status_line . ": " . $response->decoded_content;
}
};
if ( $@ ) {
print "Error: $@\n";
}
#!/usr/bin/ruby
require 'curl'
require 'curb'
require 'json'
begin
data = {
'emailAddressList': {
'email1@example.com',
'email2@example.com'
},
'startDate': '2021-08-01 00:00:00',
'endDate': '2021-08-09 23:59:59',
'reasonList': {
'OPTED_OUT'
},
'recordCount': 5000,
'recordStart': 0
}
c = Curl::Easy.new
c.url = 'https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/email/validate'
c.http_auth_types = :basic
c.username = 'SomeSecretUsername'
c.password = 'SomeSecretPassword'
c.connect_timeout = 5
c.timeout = 30
c.verbose = true
headers={}
headers['Content-Type'] = 'application/json'
headers['Content-Length'] = data.to_json.length
payload = data.to_json
c.headers = headers
c.http_post(payload)
puts JSON.parse c.body_str
if c.response_code == 200 then
puts "Success " + c.status
else
puts "Error " + c.status
end
rescue
puts "Caught: #$!\n"
end
POST
EmailBlockedSearchParameters
to search for email addresses that have been blocked
Test URL:
https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/blocked/search
Live URL:
https://notification.pdc4u.com/NotificationService/api/v1_0/emails/blocked/search
Sample Email Unblock
<?php
$url = 'https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/unblock';
$data = [
'emailAddressList' => [
'email1@example.com',
'email2@example.com'
]
];
$curl = curl_init();
curl_setopt($curl, CURLOPT_POST, 1);
$data = json_encode($data, JSON_UNESCAPED_SLASHES);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Content-Length: ' . strlen($data),
]);
curl_setopt($curl, CURLOPT_USERPWD, "someSecretUsername:someSecretPassword");
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($curl, CURLOPT_TIMEOUT, 30);
$result = curl_exec($curl);
$statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
// View response
print_r(json_decode($result, true));
if($statusCode == '200') {
echo $result;
}
else {
echo "Error #:" . $statusCode;
}
curl_close($curl);
#!/usr/bin/perl
use LWP::UserAgent;
use HTTP::Request;
use JSON::XS;
use IO::Socket::SSL qw(debug3); # verbose for troubleshooting
eval {
my $data = {
'emailAddressList' => {
'email1@example.com',
'email2@example.com'
}
}
$data = JSON::XS->new->utf8->encode ($data);
my $url = 'https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/unblock';
my $req = HTTP::Request->new( 'POST', $url );
$req->authorization_basic( 'SomeSecretUsername', 'SomeSecretPassword' );
$req->content_type('application/json');
$req->content_length( length($data) );
$req->content( $data );
my $lwp = LWP::UserAgent->new;
$lwp->timeout(30);
my $response = $lwp->request( $req );
if ( $response->is_success ) {
print "Success: " . $response->decoded_content;
}
else {
die $response->status_line . ": " . $response->decoded_content;
}
};
if ( $@ ) {
print "Error: $@\n";
}
#!/usr/bin/ruby
require 'curl'
require 'curb'
require 'json'
begin
data = {
'emailAddressList' => {
'email1@example.com',
'email2@example.com'
}
}
c = Curl::Easy.new
c.url = 'https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/unblock'
c.http_auth_types = :basic
c.username = 'SomeSecretUsername'
c.password = 'SomeSecretPassword'
c.connect_timeout = 5
c.timeout = 30
c.verbose = true
headers={}
headers['Content-Type'] = 'application/json'
headers['Content-Length'] = data.to_json.length
payload = data.to_json
c.headers = headers
c.http_post(payload)
puts JSON.parse c.body_str
if c.response_code == 200 then
puts "Success " + c.status
else
puts "Error " + c.status
end
rescue
puts "Caught: #$!\n"
end
POST
an EmailAddressList
object to unblock the email addresses
Test URL:
https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/emails/unblock
Live URL:
https://notification.pdc4u.com/NotificationService/api/v1_0/emails/unblock
Sample SMS Validate
<?php
$url = 'https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/sms/validate/1235551234';
$curl = curl_init();
curl_setopt($curl, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
"Authorization: BASIC " . base64_encode('companyUsername'.':'.'companyPassword')
]);
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 5); //num seconds to try connecting
curl_setopt($curl, CURLOPT_TIMEOUT, 30); //max number of seconds to allow execution
$result = curl_exec($curl);
$statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
// View response
print_r(json_decode($result, true));
if($statusCode == '200') {
echo $result;
}
else {
echo "Error #:" . $statusCode;
}
curl_close($curl);
#!/usr/bin/perl
use LWP::UserAgent;
use HTTP::Request;
use JSON::XS;
use IO::Socket::SSL qw(debug3); # verbose for troubleshooting
eval {
my $uri = URI->new("https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/sms/validate/1235551234");
my $req = HTTP::Request->new( 'GET', $uri );
$req->authorization_basic( 'SomeSecretUsername', 'SomeSecretPassword' );
my $lwp = LWP::UserAgent->new;
my $response = $lwp->request( $req );
if ( $response->is_success ) {
print "Success: " . $response->decoded_content;
}
else {
die $response->status_line . ": " . $response->decoded_content;
}
};
if ( $@ ) {
print "Error: $@\n";
}
#!/usr/bin/ruby
require 'curl'
require 'curb'
require 'json'
begin
url = 'https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/sms/validate/1235551234'
c = Curl::Easy.new( url )
c.http_auth_types = :basic
c.username = 'SomeSecretUsername'
c.password = 'SomeSecretPassword'
c.connect_timeout = 5
c.timeout = 30
c.verbose = true
c.perform
puts JSON.parse c.body_str
if c.response_code == 200 then
puts "Success " + c.status
else
puts "Error " + c.status
end
rescue
puts "Caught: #$!\n"
end
GET
to validate a Phone Number. This includes checking if the Phone Number has Opted Out from receiving SMS.
Test URL:
https://notificationdemo.pdc4u.com/NotificationService/api/v1_0/sms/validate/{phoneNumber}
Live URL:
https://notification.pdc4u.com/NotificationService/api/v1_0/sms/validate/{phoneNumber}