> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modulex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# PostGrid Integration for AI Agents & Workflows

> Programmatic direct mail delivery via the PostGrid Print & Mail API

{/* Self-hosted logo — build-time vendored from modulex.json / Iconify (see scripts/lib/logo.js). */}

<img src="https://mintcdn.com/modulexaillc/df8MOr-hXotYLTh5/logos/postgrid.svg?fit=max&auto=format&n=df8MOr-hXotYLTh5&q=85&s=ecffcb87fa0b0a039f552fbe510741ec" alt="PostGrid logo" width="72" height="72" data-path="logos/postgrid.svg" />

## 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`).

<Info>
  **Categories**: Marketing & Advertising · Marketing · Business Services · **Auth**: API Key · **Actions**: 3
</Info>

## Authentication

### API Key Authentication

Authenticate using your PostGrid API key

<Steps>
  <Step title="Step 1">
    Sign in at [https://app.postgrid.com](https://app.postgrid.com)
  </Step>

  <Step title="Step 2">
    Navigate to 'Settings' > 'API Keys'
  </Step>

  <Step title="Step 3">
    Copy your live or test API key
  </Step>

  <Step title="Step 4">
    Paste the API key below
  </Step>
</Steps>

#### Required Credentials

| Field            | Description                                 | Required | Format                                     |
| ---------------- | ------------------------------------------- | -------- | ------------------------------------------ |
| PostGrid API Key | Your PostGrid API key from app.postgrid.com | Yes      | `live_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |

## Available Actions

<AccordionGroup>
  <Accordion title="create_contact — Create a new contact in PostGrid">
    ### Parameters

    <ResponseField name="first_name" type="string" required>
      The first name of the contact
    </ResponseField>

    <ResponseField name="last_name" type="string">
      The last name of the contact
    </ResponseField>

    <ResponseField name="company_name" type="string">
      The contact's company name
    </ResponseField>

    <ResponseField name="address_line1" type="string" required>
      The contact's first address line
    </ResponseField>

    <ResponseField name="address_line2" type="string">
      The contact's second address line
    </ResponseField>

    <ResponseField name="city" type="string">
      The contact's city
    </ResponseField>

    <ResponseField name="province_or_state" type="string">
      The province or state of the contact
    </ResponseField>

    <ResponseField name="email" type="string">
      The contact's email address
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      The contact's phone number
    </ResponseField>

    <ResponseField name="job_title" type="string">
      The contact's job title
    </ResponseField>

    <ResponseField name="postal_or_zip" type="string">
      The postal code or ZIP code of the contact
    </ResponseField>

    <ResponseField name="country_code" type="string">
      ISO 3166-1 country code of the contact's address. Defaults to CA (Default: `CA`)
    </ResponseField>

    <ResponseField name="description" type="string">
      A description for the contact
    </ResponseField>

    <ResponseField name="skip_verification" type="boolean">
      If true, skip address verification and mark the address as failed
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$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"
    }
    ```
  </Accordion>

  <Accordion title="create_letter — Create a new letter in PostGrid">
    ### Parameters

    <ResponseField name="to" type="string" required>
      The ID or contact object of the receiver
    </ResponseField>

    <ResponseField name="from_contact" type="string" required>
      The ID or contact object of the sender
    </ResponseField>

    <ResponseField name="html" type="string" required>
      The HTML content of the letter
    </ResponseField>

    <ResponseField name="address_placement" type="string">
      Location where the address will be placed. One of: top\_first\_page, insert\_blank\_page
    </ResponseField>

    <ResponseField name="double_sided" type="boolean">
      Whether the letter is double sided
    </ResponseField>

    <ResponseField name="color" type="boolean">
      Whether the letter will be printed in color
    </ResponseField>

    <ResponseField name="perforated_page" type="integer">
      Page number to be perforated
    </ResponseField>

    <ResponseField name="extra_service" type="string">
      Extra services for the letter. One of: certified, certified\_return\_receipt, registered
    </ResponseField>

    <ResponseField name="envelope_type" type="string">
      Envelope type. One of: standard\_double\_window, flat
    </ResponseField>

    <ResponseField name="return_envelope" type="string">
      The ID of the return envelope to be used
    </ResponseField>

    <ResponseField name="send_date" type="string">
      Desired date for the letter to be sent out (ISO 8601 format)
    </ResponseField>

    <ResponseField name="description" type="string">
      A description for the letter
    </ResponseField>

    <ResponseField name="express" type="boolean">
      Whether to use express shipping
    </ResponseField>

    <ResponseField name="mailing_class" type="string">
      Mailing class. One of: standard\_class, first\_class. Defaults to first\_class
    </ResponseField>

    <ResponseField name="size" type="string">
      Letter size. One of: us\_letter, us\_legal, a4
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$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"
    }
    ```
  </Accordion>

  <Accordion title="create_postcard — Create a new postcard in PostGrid">
    ### Parameters

    <ResponseField name="to" type="string" required>
      The ID or contact object of the receiver
    </ResponseField>

    <ResponseField name="from_contact" type="string" required>
      The ID or contact object of the sender
    </ResponseField>

    <ResponseField name="front_html" type="string" required>
      The HTML content for the front of the postcard
    </ResponseField>

    <ResponseField name="back_html" type="string" required>
      The HTML content for the back of the postcard
    </ResponseField>

    <ResponseField name="size" type="string" required>
      Postcard size. One of: 6x4, 9x6, 11x6
    </ResponseField>

    <ResponseField name="send_date" type="string">
      Desired date for the postcard to be sent out (ISO 8601 format)
    </ResponseField>

    <ResponseField name="express" type="boolean">
      Whether to use express shipping
    </ResponseField>

    <ResponseField name="description" type="string">
      A description for the postcard
    </ResponseField>

    <ResponseField name="mailing_class" type="string">
      Mailing class. One of: standard\_class, first\_class. Defaults to first\_class
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$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"
    }
    ```
  </Accordion>
</AccordionGroup>

## 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.

## Related integrations

<CardGroup cols={3}>
  <Card title="Ahrefs" href="/integrations/tools/ahrefs" />

  <Card title="Google Ad Manager" href="/integrations/tools/google-ad-manager" />

  <Card title="Google Ads" href="/integrations/tools/google-ads" />
</CardGroup>

## Links

* [PostGrid](https://www.postgrid.com)