NAV
shell

Introduction

Mailform is the easiest way to send FedEx Standard Overnight, USPS Priority, Express & First Class Mail right from your computer, and now using our API you can integrate Mailform's advanced print and mail functionality into your programs.

We have code examples in the dark area to the right: these are currently shown using the Curl command line utility, but other langauges will be added in the near future. As those become available, you'll be able to switch the programming language of the examples with the tabs in the top right.

Frequently Asked Questions

How much does it cost?

There is no cost associated with accessing the Mailform API. Mail sent with the API will incur charges.

How much do print and mail orders cost?

Please visit our pricing page at https://www.mailform.io/pricing for detailed pricing information.

Do I need to sign up or create an account?

Yes. To use the Mailform API, you will need to sign up at https://www.mailform.io/login.html#register.

Is there a recurring or subscription fee associated with the API.

No. You will only be charged for the letters and postcards you send, nothing more. You may choose to receive a receipt by email for each letter sent.

What if I am sending a lot of letters?

Contact us! Send us a message, email us at support@mailform.io, or call us at 805-395-9596.

Authentication

Mailform uses API keys to allow access to the API. You can create a new Mailform API key from your account page at https://www.mailform.io/webapp/account.html#/api.

The Mailform API requires that the API key be included in all API requests, using the Authorization header:

Authorization: Bearer {api key}

API keys can be created in test mode: any orders placed by a test mode API key will be automatically cancelled and will incur no charges.

API Interactions

All API responses will include a Content-Type header: by default, all API responses will use the application/json response format.

{
  "success": true,
  "data": <payload>
}

Successful API responses will include a success field set to true. By default the payload will be a JSON object, with an object field set to a specific value, appropriate to the API call. For certain API calls, the response will be a JSON array: those responses will include an object field in the response set to list.

 
{
  "error": {
    "code": "erroroccurred",
    "message": "user_not_found"
  }
}

Failed API responses will include an error object with a code field containing a generic error code and a message field with more details information.

All timestamps will be returned in ISO8601 format.

Address

Address Resource

{
        "object": "address",
        "address1": "607 North Avenue",
        "city": "Wakefield",
        "state": "MA",
        "postcode": "01880",
        "country": "United States",
        "formatted": "607 North Avenue Door 18, Wakefield MA 01880, United States",
        "id": "e8ea8dc5-d199-481d-87e3-8c3189407b25",
        "is_default": true,
        "address2": "Door 18"
}

Represents information about an address.

Field Type Description
object string The type of object (address)
id string The identifier of the address
name string The name of the person associated with this address
organization string The organization or company associated with this address
address1 string The street number and name
address2 string The suite or room number
city string The address city
state string The address state
postcode string The address postcode or zip code
country string The address country
formatted string The fully formatted address, combining all the parts of the address.
is_default boolean Indicates that this is the default address to use (only present when the address is returned as part of a user object)

Balance

Balance Resource

{
      "object": "balance",
      "id": "9dd73fb2-a47a-4d04-8e06-1878b66dc324",
      "amount": 20368,
      "currency": "USD"
}

Represents information about a prepaid account balance.

Field Type Description
object string The type of object (balance)
id string The identifier of the prepaid account balance
amount integer The prepaid account balance, in the smallest units of the balance's currency (i.e. cents for USD-denominated balances)
currency string The currency of the prepaid account balance

Cost Component

Cost Component Resource

{
      "type": "base",
      "value": 299
}

Represents information about a line item cost component.

Field Type Description
type string The price component name
amount integer The amount of the cost component, in the smallest units of the balance's currency (i.e. cents for USD-denominated balances)

Line Item

Line Item Resource

{
      "object": "lineitem",
      "id": "aa582708-65dd-4094-8b13-5699a6e8fdb4",
      "pagecount": 3,
      "to": {
        "name": "Frank White",
        "address1": "607 North Avenue",
        "address2": "Door 18",
        "city": "Wakefield",
        "state": "MA",
        "postcode": "01880",
        "country": "US",
        "formatted": "607 North Avenue Door 18, Wakefield MA, US",
        "organization": "Mailform, Inc."
      },
      "from": {
        "name": "Joe Green",
        "address1": "607 North Avenue",
        "address2": "Door 18",
        "city": "Wakefield",
        "state": "MA",
        "postcode": "01880",
        "country": "US",
        "formatted": "607 North Avenue Door 18, Wakefield MA, US",
        "organization": "Mailform, Inc."
      },
      "simplex": true,
      "color": false,
      "service": "USPS_FIRST_CLASS",
      "pricing": [
        {
          "type": "base",
          "value": 299
        },
        {
          "type": "additional",
          "value": 98
        },
        {
          "type": "simplex",
          "value": 98
        }
      ]
}

Represents information about an envelope or postcard

Field Type Description
object string The type of object (lineitem)
id string The identifier of the line item
pagecount integer The number of pages in the line item
to object (Address) The recipient address
from object (Address) The sender address
simplex boolean True if the document should be printed one page to a sheet, false if the document can be printed on both sides of a sheet
color boolean True if the document should be printed in color, false if the document should be printed in black and white
flat boolean True if the document MUST be mailed in a flat envelope, false if it is acceptable to mail the document folded
stamp boolean True if the document MUST use a real postage stamp, false if it is acceptable to mail the document using metered postage or an imprint
service string Yes
pricing array (Cost Component) An array of cost components that provide the pricing of this line item.
message string The message to be printed on the non-picture side of a postcard.
tracking_number string The tracking number for the envelope

The message is only applicable when the service field is set to USPS_POSTCARD.

Setting flat to true is only applicable when the service field is set to one of USPS_CERTIFIED_PHYSICAL_RECEIPT, USPS_CERTIFIED_RECEIPT, USPS_CERTIFIED, or USPS_FIRST_CLASS.

Setting stamp to true is only applicable when the service field is set to USPS_FIRST_CLASS.

The tracking_number field will only be available after fulfillment of orders where the service field is set one of FEDEX_OVERNIGHT, USPS_PRIORITY_EXPRESS, USPS_PRIORITY, USPS_CERTIFIED_PHYSICAL_RECEIPT, USPS_CERTIFIED_RECEIPT or USPS_CERTIFIED.

Users

User Resource

{
    "object": "user",
    "id": "712c8bc5-f2c6-4235-a23e-3f90acc02821",
    "email": "support@mailform.io",
    "name": "Frank White",
    "addresses": [
      {
        "address1": "607 North Avenue",
        "city": "Wakefield",
        "state": "MA",
        "zip": "01880",
        "country": "United States",
        "formatted": "607 North Avenue Door 18, Wakefield MA 01880, United States",
        "id": "e8ea8dc5-d199-481d-87e3-8c3189407b25",
        "is_default": true,
        "address2": "Door 18"
      }
    ],
    "balance": {
      "object": "balance",
      "id": "9dd73fb2-a47a-4d04-8e06-1878b66dc324",
      "amount": 20368,
      "currency": "USD"
    }
  }

Represents information about a user

Field Type Description
object string The type of object (user)
id string The identifier of the currently authenticated user
email email address The email address of the currently authenticated user
name string The name of the currently authenticated user
addresses array An array of the addresses saved for the currently authenticated user
balance object The user's prepaid account balance

Get Current User

curl "https://www.mailform.io/app/api/v1/users/me" \
  -H "Authorization: {api key}"

Example response:

{
  "success": true,
  "data": {
    "object": "user",
    "id": "712c8bc5-f2c6-4235-a23e-3f90acc02821",
    "email": "support@mailform.io",
    "name": "Frank White",
    "addresses": [
      {
        "address1": "607 North Avenue",
        "city": "Wakefield",
        "state": "MA",
        "zip": "01880",
        "country": "United States",
        "formatted": "607 North Avenue Door 18, Wakefield MA 01880, United States",
        "id": "e8ea8dc5-d199-481d-87e3-8c3189407b25",
        "is_default": true,
        "address2": "Door 18"
      }
    ],
    "balance": {
      "object": "balance"
      "id": "9dd73fb2-a47a-4d04-8e06-1878b66dc324",
      "amount": 20368,
      "currency": "USD",
    }
  }
}

Retrieve the user information for the user associated with the API token used for authorization.

HTTP Request

GET https://www.mailform.io/app/api/v1/users/me

Parameters

None

Authorization

Required

Teams

Team Resource

{
    "object": "team",
    "id": "5b5f47f0-a7b3-4d43-b0e2-41bcf3170af6",
    "name": "Mailform Inc.",
    "owner": true,
    "joined": "2019-02-05T18:54:50.413Z",
    "balance": {
        "object": "balance",
        "id": "9dd73fb2-a47a-4d04-8e06-1878b66dc324",
        "amount": 20368,
        "currency": "USD"
      }
}

Represents information about a team

Field Type Description
object string The type of object (team)
id string The identifier of the team or company
name string The name of the team or company
owner boolean Whether or not the authenticated user is considered to be a team owner
joined datetime When the authenticated user joined the team
balance object The prepaid account balance associated with the team

Get All Teams

curl "https://www.mailform.io/app/api/v1/teams" \
  -H "Authorization: {api key}"

Example response:

{
  "success": true,
  "object": "list",
  "data": [
    {
      "object": "team",
      "id": "2543d0ff-fff1-4f71-8993-f2c5701f6b6f",
      "name": "Mailform Inc",
      "owner": true,
      "joined": "2020-12-04T21:40:33.981Z",
      "balance": {
        "object": "balance",
        "id": "9dd73fb2-a47a-4d04-8e06-1878b66dc324",
        "amount": 20368,
        "currency": "USD"
      }
    },
    {
      "object": "team",
      "id": "3256f854-d899-4ddf-b1d3-d5b5951f16e8",
      "name": "Test Business",
      "owner": true,
      "joined": "2020-12-04T21:40:33.981Z",
      "balance": {
        "object": "balance",
        "id": "e91583a1-843f-47af-bd52-c34284dfa8c0",
        "amount": 1820,
        "currency": "USD"
      }
    },
    {
      "object": "team",
      "id": "f8203f14-bbf5-43ae-9012-eb471a3ccc10",
      "name": "Partnerships",
      "owner": true,
      "joined": "2020-12-04T21:40:33.981Z",
      "balance": {
        "object": "balance",
        "id": "140c9c23-eed2-45a5-82cb-9dcc66dbf315",
        "amount": 155689,
        "currency": "USD"
      }
    }
  ]
}

Retrieve a list of all the teams the authenticated user is a member of.

Parameters

None

Authorization

Required

Get A Specific Team

curl "https://www.mailform.io/app/api/v1/teams/2543d0ff-fff1-4f71-8993-f2c5701f6b6f" \
  -H "Authorization: {api key}"

Example response:

{
  "success": true,
  "data": {
      "object": "team",
      "id": "2543d0ff-fff1-4f71-8993-f2c5701f6b6f",
      "name": "Mailform Inc",
      "owner": true,
      "joined": "2020-12-04T21:40:33.981Z",
      "balance": {
        "object": "balance",
        "id": "9dd73fb2-a47a-4d04-8e06-1878b66dc324",
        "amount": 20368,
        "currency": "USD"
      }
   }
}

Retrieves a specific team that the authenticated user is a member of.

HTTP Request

GET https://www.mailform.io/app/api/v1/teams/:team_id

Parameters

Field Type Requires Description
team_id string Yes The id of the team to be retrieved

Authorization

Required

Orders

Orders Resource

{
  "object": "order",
  "id": "7acc31fc-dc48-41e5-bf73-d495436afc6e",
  "created": "2021-06-04T15:31:29.508Z",
  "total": 495,
  "modified": "2021-06-04T15:31:29.894Z",
  "webhook": "https://testing.mailform.io:9000/",
  "lineitems": [
    {
      "id": "aa582708-65dd-4094-8b13-5699a6e8fdb4",
      "pagecount": 3,
      "to": {
        "name": "Frank White",
        "address1": "607 North Avenue",
        "address2": "Door 18",
        "city": "Wakefield",
        "state": "MA",
        "postcode": "01880",
        "country": "US",
        "formatted": "607 North Avenue Door 18, Wakefield MA, US",
        "organization": "Mailform, Inc."
      },
      "from": {
        "name": "Joe Green",
        "address1": "607 North Avenue",
        "address2": "Door 18",
        "city": "Wakefield",
        "state": "MA",
        "postcode": "01880",
        "country": "US",
        "formatted": "607 North Avenue Door 18, Wakefield MA, US",
        "organization": "Mailform, Inc."
      },
      "simplex": true,
      "color": false,
      "service": "USPS_FIRST_CLASS",
      "pricing": [
        {
          "type": "base",
          "value": 299
        },
        {
          "type": "additional",
          "value": 98
        },
        {
          "type": "simplex",
          "value": 98
        }
      ]
    }
  ],
  "account": "712c8bc5-f2c6-4235-a23e-3f90acc02821",
  "customer_reference": "TEST1",
  "channel": "api",
  "test_mode": true,
  "state": "cancelled",
  "cancelled": "2021-06-04T15:31:29.468Z",
  "cancellation_reason": "Test mode order: automatically cancelled"
}

Represents information about a team

Field Type Description
object string The type of object (order)
id string The identifier of the currently authenticated user
created datetime When the order was created
modified datetime When the order was last modified or updated
total integer The cost in cents of the order
webhook string The webhook that should receive notifications about order updates
account string The user account that created the order
company string The company that the order is associated with (if any)
channel string The channel that was used to place the order. Can be one of api or web
state string The state the order is in. Will be one of queued, awaiting_fulfillment, fulfilled or cancelled
test_mode boolean True if the order was placed using a test mode API key
cancelled datetime If the order was cancelled, the date and time that the order was cancelled
cancellation_reason string If the order was cancelled, the reason provided for cancelling the order
customer_reference string An optional customer reference provided when the order was placed
lineitems array (Line Item) The list of line items (envelopes or postcards) to be mailed in this order.

Create Order

curl -v https://www.mailform.io/app/api/v1/orders /
-F 'file=@{orderfile}' /
-F 'customer_reference=TEST1' /
-F 'service=USPS_FIRST_CLASS' /
-F 'to.name=Frank White' /
-F 'to.organization=Mailform, Inc.' /
-F 'to.address1=607 North Avenue' /
-F 'to.address2=Door 18' /
-F 'to.city=Wakefield' /
-F 'to.state=MA' /
-F 'to.postcode=01880' /
-F 'to.country=US' /
-F 'from.name=Joe Green' /
-F 'from.organization=Mailform, Inc.' /
-F 'from.address1=607 North Avenue' /
-F 'from.address2=Door 18' /
-F 'from.city=Wakefield' /
-F 'from.state=MA' /
-F 'from.postcode=01880' /
-F 'from.country=US' /
-F 'simplex=true' /
-F 'webhook={webhook url}' /
-H "Authorization: Bearer {api key}" 

Example response:

{
  "success": true,
  "data": {
    "object": "order",
    "id": "af91e239-0c5c-40b5-bab8-1f4271acba72",
    "created": "2021-06-07T05:19:02.906Z",
    "total": 495,
    "webhook": "{webhook url}",
    "lineitems": [
      {
        "id": "160f563a-f481-4b64-8012-5902a540dfd7",
        "to": {
          "name": "Frank White",
          "address1": "607 North Avenue",
          "address2": "Door 18",
          "city": "Wakefield",
          "state": "MA",
          "postcode": "01880",
          "country": "US",
          "formatted": "607 North Avenue Door 18, Wakefield MA, US",
          "organization": "Mailform, Inc."
        },
        "from": {
          "name": "Joe Green",
          "address1": "607 North Avenue",
          "address2": "Door 18",
          "city": "Wakefield",
          "state": "MA",
          "postcode": "01880",
          "country": "US",
          "formatted": "607 North Avenue Door 18, Wakefield MA, US",
          "organization": "Mailform, Inc."
        },
        "simplex": true,
        "color": false,
        "service": "USPS_FIRST_CLASS",
        "pricing": [
          {
            "type": "base",
            "value": 299
          },
          {
            "type": "additional",
            "value": 98
          },
          {
            "type": "simplex",
            "value": 98
          }
        ]
      }
    ],
    "account": "712c8bc5-f2c6-4235-a23e-3f90acc02821",
    "customer_reference": "TEST1",
    "channel": "api",
    "test_mode": true,
    "state": "cancelled",
    "cancelled": "2021-06-07T05:19:02.885Z",
    "cancellation_reason": "Test mode order: automatically cancelled"
  }
}

Creates a new order.

HTTP Request

POST https://www.mailform.io/app/api/v1/orders

The request MUST be have Content-Type set to multipart/form.

Parameters

Field Type Requires Description
file File Yes The PDF document to be mailed
customer_reference string No An optional customer reference to be attached to the order
service string Yes The delivery service to be used. Must be one of FEDEX_OVERNIGHT, USPS_PRIORITY_EXPRESS, USPS_PRIORITY, USPS_CERTIFIED_PHYSICAL_RECEIPT, USPS_CERTIFIED_RECEIPT, USPS_CERTIFIED, USPS_FIRST_CLASS, USPS_STANDARD or USPS_POSTCARD.
webhook string No The webhook that should receive notifications about order updates to this order
company string No The company that this order should be associated with
simplex boolean No True if the document should be printed one page to a sheet, false if the document can be printed on both sides of a sheet
color boolean No True if the document should be printed in color, false if the document should be printed in black and white
flat boolean No True if the document MUST be mailed in a flat envelope, false if it is acceptable to mail the document folded
stamp boolean No True if the document MUST use a real postage stamp, false if it is acceptable to mail the document using metered postage or an imprint
message string No The message to be printed on the non-picture side of a postcard.
to.name string Yes The name of the recipient of this envelope or postcard
to.organization string No The organization or company associated with the recipient of this envelope or postcard
to.address1 string Yes The street number and name of the recipient of this envelope or postcard
to.address2 string No The suite or room number of the recipient of this envelope or postcard
to.city string Yes The address city of the recipient of this envelope or postcard
to.state string Yes The address state of the recipient of this envelope or postcard
to.postcode string Yes The address postcode or zip code of the recipient of this envelope or postcard
to.country string Yes The address country of the recipient of this envelope or postcard
from.name string Yes The name of the sender of this envelope or postcard
from.organization string No The organization or company associated with this address
from.address1 string Yes The street number and name of the sender of this envelope or postcard
from.address2 string No The suite or room number of the sender of this envelope or postcard
from.city string Yes The address city of the sender of this envelope or postcard
from.state string Yes The address state of the sender of this envelope or postcard
from.postcode string Yes The address postcode or zip code of the sender of this envelope or postcard
from.country string Yes The address country of the sender of this envelope or postcard

Authorization

Required

Get Order

curl -v -H "Authorization: Bearer {api key}" /
https://www.mailform.io/app/api/v1/orders/af91e239-0c5c-40b5-bab8-1f4271acba72

Example response:

{
  "success": true,
  "data": {
    "object": "order",
    "id": "af91e239-0c5c-40b5-bab8-1f4271acba72",
    "created": "2021-06-07T05:19:02.906Z",
    "total": 495,
    "modified": "2021-06-07T05:19:03.286Z",
    "webhook": "https://rbaskets.in/kx9d7q8",
    "lineitems": [
      {
        "id": "160f563a-f481-4b64-8012-5902a540dfd7",
        "pagecount": 3,
        "to": {
          "name": "Frank White",
          "address1": "607 North Avenue",
          "address2": "Door 18",
          "city": "Wakefield",
          "state": "MA",
          "postcode": "01880",
          "country": "US",
          "formatted": "607 North Avenue Door 18, Wakefield MA, US",
          "organization": "Mailform, Inc."
        },
        "from": {
          "name": "Joe Green",
          "address1": "607 North Avenue",
          "address2": "Door 18",
          "city": "Wakefield",
          "state": "MA",
          "postcode": "01880",
          "country": "US",
          "formatted": "607 North Avenue Door 18, Wakefield MA, US",
          "organization": "Mailform, Inc."
        },
        "simplex": true,
        "color": false,
        "service": "USPS_FIRST_CLASS",
        "pricing": [
          {
            "type": "base",
            "value": 299
          },
          {
            "type": "additional",
            "value": 98
          },
          {
            "type": "simplex",
            "value": 98
          }
        ]
      }
    ],
    "account": "712c8bc5-f2c6-4235-a23e-3f90acc02821",
    "customer_reference": "TEST1",
    "channel": "api",
    "test_mode": true,
    "state": "cancelled",
    "cancelled": "2021-06-07T05:19:02.885Z",
    "cancellation_reason": "Test mode order: automatically cancelled"
  }
}

Retrieves an existing order.

HTTP Request

GET https://www.mailform.io/app/api/v1/orders/:order_id

The request MUST be have Content-Type set to multipart/form.

Parameters

Field Type Requires Description
order_id string Yes The id of the order to be retrieved

Authorization

Required

Errors

The Mailform API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The method requested is not accessible to the provided API key.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access a resource with an invalid method.
406 Not Acceptable -- You requested a format that isn't supported.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.