Before we can get started with sending mails, we will need to specify who the mails are from and who they are going to. Although contact creation may be easily done using the dashboard, PostGrid still offers the ability to create and view contacts directly from the API.

Creating New Contacts

Before we can make a new contact, we need to know what information a contact consists of.

Using the above image or the example image of contact details found in the 'Adding Variables to Templates' section, we have a guide as to what type of information we will need to send in order to create a contact. In the above list, every field except for 'id', 'object', 'live', and 'addressStatus' are specified upon creation of the contact. Of the fields which pertain to an address, not every field needs to be filled out in order to create the contact as PostGrid can verify and parse the address in order to take a single line address and fill out the contact's individual address fields.

To keep things simple, let's create a function to create a contact with a certain first and last name, give them a description, and the address in one line. Looking at our API documentation, we need to make a POST request to /contacts, so let's do so.

const fetch = require('node-fetch');

const POSTGRID_URL = 'https://api.postgrid.com/print-mail/v1';

const API_KEY = '' // Place your API key here

/**
 * @param {string} firstName
 * @param {string} lastName
 * @param {string} description
 * @param {string} address
 */
async function createContact(firstName, lastName, description, address) {
    const requestOptions = {
        method: 'POST',
        headers: {
            'x-api-key': API_KEY,
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            firstName: firstName,
            lastName: lastName,
            description: description,
            addressLine1: address,
        }),
    };

    const resp = await fetch(POSTGRID_URL + '/contacts', requestOptions);

    return await resp.json();
}

Running through the information 'John', 'Smith', 'This is a test contact', and '200 University Ave W, Waterloo, Ontario', we receive back the following.

{
    "id": "contact_vG8h8EKBM5ZSfGBpCcSACd",
    "object": "contact",
    "live": false,
    "addressLine1": "3075 14TH AVE 212",
    "addressLine2": "",
    "addressStatus": "verified",
    "city": "MARKHAM",
    "country": "CANADA",
    "countryCode": "CA",
    "firstName": "John",
    "lastName": "Smith",
    "postalOrZip": "L3R0G9",
    "provinceOrState": "ON",
    "createdAt": "2021-09-07T15:22:13.956Z",
    "updatedAt": "2021-09-07T15:22:13.956Z"
}

Notice that the address information is completely different than what we entered. This is because we used our test key, so the contact will be in test mode and have this default address which is set to verified by default. Running this API call again with our live key, we will instead get what's below.

{
    "id": "contact_eakam7BFaxchRD65WsPgVG",
    "object": "contact",
    "live": true,
    "addressLine1": "200 UNIVERSITY AVE W",
    "addressLine2": "",
    "addressStatus": "corrected",
    "city": "WATERLOO",
    "country": "CANADA",
    "countryCode": "CA",
    "firstName": "John",
    "lastName": "Smith",
    "postalOrZip": "N2L 3G1",
    "provinceOrState": "ON",
    "createdAt": "2021-09-07T15:47:04.214Z",
    "updatedAt": "2021-09-07T15:47:04.214Z"
}

Now our addressStatus is 'corrected' to fill in our missing information such as the country and postal code and the address information reflects what we sent the server.

When it comes to contact creation, do remember that we can fill-out the address information directly or add more data to our contacts such as 'jobTitle' or 'companyName'. The fields added to our contact here were just for simplicity.

Viewing Contacts

As with templates, we have very similar options for viewing contacts. We may either examine an individual contact by sending a GET request to /contacts/:id, or list contacts by sending a GET request to /contacts. As these work so similarly to their equivalent requests to /templates and /letters, we will only show a brief function for retrieving contact information with a given first and last name.

/**
 * @param {string} firstName
 * @param {string} lastName
 */
async function retrieveContactByName(firstName, lastName) {
    const requestOptions = {
        method: 'GET',
        headers: {
            'x-api-key': API_KEY,
        },
    };

    const searchString = encodeURIComponent(
        JSON.stringify({
            firstName: firstName,
            lastName: lastName,
        })
    );

    const queryString = `?skip=0&limit=1&search=${searchString}`;

    const resp = await fetch(
        POSTGRID_URL + '/contacts' + queryString,
        requestOptions
    );

    const searchResults = await resp.json();

    if (searchResults.totalCount === 0) {
        throw new Error('No such contact with given name');
    }

    return searchResults.data[0];
}

API Reference: https://postgrid.readme.io/reference/contacts