Skip to main content
PostGrid logo

​
Overview

Add PostGrid to any ModuleX agent or workflow. Programmatic direct mail delivery via the PostGrid Print & Mail API (api.postgrid.com/print-mail/v1).
Categories: Marketing & Advertising · Marketing · Business Services · Auth: API Key · Actions: 3

​
Authentication

​
API Key Authentication

Authenticate using your PostGrid API key
1

Step 1

Sign in at https://app.postgrid.com
2

Step 2

Navigate to ‘Settings’ > ‘API Keys’
3

Step 3

Copy your live or test API key
4

Step 4

Paste the API key below

​
Required Credentials

FieldDescriptionRequiredFormat
PostGrid API KeyYour PostGrid API key from app.postgrid.comYeslive_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

​
Available Actions

​
Parameters

​
first_name
string
required
The first name of the contact
​
last_name
string
The last name of the contact
​
company_name
string
The contact’s company name
​
address_line1
string
required
The contact’s first address line
​
address_line2
string
The contact’s second address line
​
city
string
The contact’s city
​
province_or_state
string
The province or state of the contact
​
email
string
The contact’s email address
​
phone_number
string
The contact’s phone number
​
job_title
string
The contact’s job title
​
postal_or_zip
string
The postal code or ZIP code of the contact
​
country_code
string
ISO 3166-1 country code of the contact’s address. Defaults to CA (Default: CA)
​
description
string
A description for the contact
​
skip_verification
boolean
If true, skip address verification and mark the address as failed

​
Response

{
  "$defs": {
    "ContactResource": {
      "additionalProperties": false,
      "description": "A contact object returned by the PostGrid API.",
      "properties": {
        "id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Id"
        },
        "object": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Object"
        },
        "live": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Live"
        },
        "first_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "First Name"
        },
        "last_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Last Name"
        },
        "company_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Company Name"
        },
        "address_line1": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Address Line1"
        },
        "address_line2": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Address Line2"
        },
        "city": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "City"
        },
        "province_or_state": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Province Or State"
        },
        "postal_or_zip": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Postal Or Zip"
        },
        "country": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Country"
        },
        "country_code": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Country Code"
        },
        "email": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Email"
        },
        "phone_number": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Phone Number"
        },
        "job_title": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Job Title"
        },
        "description": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Description"
        },
        "address_status": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Address Status"
        }
      },
      "title": "ContactResource",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Error"
    },
    "contact": {
      "anyOf": [
        {
          "$ref": "#/$defs/ContactResource"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "success"
  ],
  "title": "CreateContactOutput",
  "type": "object"
}

​
Parameters

​
to
string
required
The ID or contact object of the receiver
​
from_contact
string
required
The ID or contact object of the sender
​
html
string
required
The HTML content of the letter
​
address_placement
string
Location where the address will be placed. One of: top_first_page, insert_blank_page
​
double_sided
boolean
Whether the letter is double sided
​
color
boolean
Whether the letter will be printed in color
​
perforated_page
integer
Page number to be perforated
​
extra_service
string
Extra services for the letter. One of: certified, certified_return_receipt, registered
​
envelope_type
string
Envelope type. One of: standard_double_window, flat
​
return_envelope
string
The ID of the return envelope to be used
​
send_date
string
Desired date for the letter to be sent out (ISO 8601 format)
​
description
string
A description for the letter
​
express
boolean
Whether to use express shipping
​
mailing_class
string
Mailing class. One of: standard_class, first_class. Defaults to first_class
​
size
string
Letter size. One of: us_letter, us_legal, a4

​
Response

{
  "$defs": {
    "LetterResource": {
      "additionalProperties": false,
      "description": "A letter object returned by the PostGrid API.",
      "properties": {
        "id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Id"
        },
        "object": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Object"
        },
        "live": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Live"
        },
        "send_date": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Send Date"
        },
        "status": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Status"
        },
        "url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Url"
        }
      },
      "title": "LetterResource",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Error"
    },
    "letter": {
      "anyOf": [
        {
          "$ref": "#/$defs/LetterResource"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "success"
  ],
  "title": "CreateLetterOutput",
  "type": "object"
}

​
Parameters

​
to
string
required
The ID or contact object of the receiver
​
from_contact
string
required
The ID or contact object of the sender
​
front_html
string
required
The HTML content for the front of the postcard
​
back_html
string
required
The HTML content for the back of the postcard
​
size
string
required
Postcard size. One of: 6x4, 9x6, 11x6
​
send_date
string
Desired date for the postcard to be sent out (ISO 8601 format)
​
express
boolean
Whether to use express shipping
​
description
string
A description for the postcard
​
mailing_class
string
Mailing class. One of: standard_class, first_class. Defaults to first_class

​
Response

{
  "$defs": {
    "PostcardResource": {
      "additionalProperties": false,
      "description": "A postcard object returned by the PostGrid API.",
      "properties": {
        "id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Id"
        },
        "object": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Object"
        },
        "live": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Live"
        },
        "send_date": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Send Date"
        },
        "status": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Status"
        },
        "size": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Size"
        },
        "url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Url"
        }
      },
      "title": "PostcardResource",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "success": {
      "title": "Success",
      "type": "boolean"
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Error"
    },
    "postcard": {
      "anyOf": [
        {
          "$ref": "#/$defs/PostcardResource"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "required": [
    "success"
  ],
  "title": "CreatePostcardOutput",
  "type": "object"
}

​
Limits & Quotas

  • No publicly documented rate limits. PostGrid applies per-account request limits based on plan tier.
  • Sending physical mail incurs per-item costs based on the PostGrid pricing plan.
  • Error model: non-2xx responses and timeouts are caught and returned as success=False + error rather than raising.

Ahrefs

Google Ad Manager

Google Ads