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 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-calculator for detailed pricing information.

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?

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.

You must replace {api key} with your personal API key.

API Interactions

All API responses will include a Content-Type header: 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
address3	string	Additional address information
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
return_envelope	boolean	True if the document MUST have a return envelope included.
return_envelope_slip_info	array (Return Envelope Slip Info)	Present if the *return_envelope* field is true. Contains an array of caption/values that are printed on the perforated return envelope slip.
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
bank_account	string	The identifier of the bank account for the check associated with this order. Only populated on orders with checks.
amount	number	The amount of the check associated with this order, in cents. Only populated on orders with checks.
check_name	number	The name of the recipient of the check associated with this order. Only populated on orders with checks.
check_number	number	The number of the check associated with this order. Only populated on orders with checks.
check_memo	string	The memo line for the check associated with this order. Only populated on orders with checks.

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

The return_envelope_slip_info field will only be present when the return_envelope field is set to true.

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 UPS_NEXT_DAY_AIR, FEDEX_OVERNIGHT, USPS_PRIORITY_EXPRESS, USPS_PRIORITY, USPS_CERTIFIED_PHYSICAL_RECEIPT, USPS_CERTIFIED_RECEIPT or USPS_CERTIFIED, and is typically available after 1 business day (there may be additional delays for orders placed on Sunday or on USPS postal holidays).

Pricing

Order Pricing Information

{
              "lineitems": [
              {
              "type": "base",
              "value": 200
              },
              {
              "type": "returnenvelope",
              "value": 50
              }
              ],
              "cost": 250,
              "tax": 16,
              "total": 266
              }

Represents the price of an order.

Field	Type	Description
lineitems	array (Cost Component)	Contains an array of the individual cost components that build up the cost of this order.
cost	number	The cost of this order in cents
tax	number	The tax applicable if this order is purchased, based on the default billing address of the account or company linked to the API key that requested this price.
total	number	The sum of the cost and the tax (if any) that will be charged if an order matching the provided request parameters is placed.

Note that pricing for certain orders is subject to change based on availability and order timing.

Return Envelope Slip Line

Return Envelope Slip Line Resource

{
              "caption": "Customer Name",
              "value": "Frank White"
              }

Represents information about a line on the perforated return envelope slip.

Field	Type	Description
caption	string	The label for this line on the perforated return envelope slip
value	string	The value for this line on the perforated return envelope slip
type	string	(Optional) The type of line: the only values that will be returned are qrcode.url or qrcode.message.

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 an order

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 (unless the url parameter is provided)	The PDF document to be mailed. If this is not specified, the url parameter must be provided. If both the file parameter and the url parameter are provided, the url parameter will be ignored. Note: the maximum supported file size is 40MB.
url	string	No (unless the file parameter is *NOT* provided)	The URL of the PDF document to be mailed: it will be downloaded completely before the API call completes. The download must complete within 30 seconds. If this is not specified, the file parameter must be provided. If both the file parameter and the url parameter are provided, the url parameter will be ignored
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 *UPS_NEXT_DAY_AIR, FEDEX_OVERNIGHT, USPS_PRIORITY_EXPRESS, USPS_PRIORITY, USPS_CERTIFIED_PHYSICAL_RECEIPT, USPS_CERTIFIED_RECEIPT, USPS_CERTIFIED, USPS_FIRST_CLASS, USPS_STANDARD, USPS_POSTCARD, or USPS_NOTECARD*.
webhook	string	No	The webhook that should receive notifications about order updates to this order
company	string	No	The company ID that this order should be associated with: visible at your company settings page.
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
return_envelope	boolean	No	True if the document MUST be mailed with a return envelope. Do not specify if no return envelope is needed
return_envelope_slip_info.{index}.caption	string	No	An optional caption for a line added to the perforated return envelope slip. Only parsed when the *return_envelope* field is set to true, AND a matching *return_envelope_slip_info.{index}.value* field is present. Valid {index} values range from 0 to 4.
return_envelope_slip_info.{index}.value	string	No	An optional value for a line added to the perforated return envelope slip. Only parsed when the *return_envelope* field is set to true, AND a matching *return_envelope_slip_info.{index}.caption* field is present. Valid {index} values range from 0 to 4.
message	string	No	The message to be printed on the non-picture side of a postcard. Required if the service is set to *USPS_POSTCARD* or *USPS_NOTECARD*.
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
bank_account	string	No	The identifier of the bank account for the check associated with this order. Required if a check is to be included in this order.
amount	number	No	The amount of the check associated with this order, in cents. Required if a check is to be included in this order.
check_name	string	No	The name of the recipient of the check associated with this order. Required if a check is to be included in this order.
check_number	number	No	The number of the check associated with this order. Required if a check is to be included in this order.
check_memo	string	No	The memo line for the check associated with this order.

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

Get Rate

curl -v https://www.mailform.io/app/api/v1/rates /
              -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,
              "pricing": {
              "lineitems": [
              {
              "type": "base",
              "value": 200
              },
              {
              "type": "returnenvelope",
              "value": 50
              }
              ],
              "cost": 250,
              "tax": 16,
              "total": 266
              }
              }

Retrieves the pricing for a potential order. The parameters are identical to those for the Create Order endpoint.

HTTP Request

GET https://www.mailform.io/app/api/v1/rates

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

Parameters

Identical to the Create Order endpoint.

Authorization

Required

Webhooks

The Mailform API provides webhooks as an easy way to receive notifications of specific mail events.

Supported Events

Event Type	Description
EVENT_CREATED	An order is created successfully.
EVENT_CANCELLED	An order is cancelled successfully.
EVENT_TRACKING_NUMBER_AVAILABLE	The tracking number is now available for an envelope (only available on orders that have tracking numbers).

Event Resource

The webhook URL associated with the order is called using the HTTP POST method. The payload is a JSON object: the Content-Type header will be set to application/json.

Note: the response to the webhook must be received within 10 seconds.

Note: we will attempt to deliver webhooks as soon as possible after the event occurs, however some delays may occur.

Field	Type	Description
event	string	The specific event that occurred.
data	object	An Order resource

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 incorrect or unrecognized.
403	Forbidden -- The method requested is not accessible to the provided API key.
404	Not Found -- The specified resource could not be found or is inaccessible to the provided API key.
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.

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.

Introduction

Frequently Asked Questions

How much does it cost?

How much do print and mail orders cost?

Do I need to sign up or create an account?

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

What if I am sending a lot of letters?

Authentication

API Interactions

Address

Address Resource

Balance

Balance Resource

Cost Component

Cost Component Resource

Line Item

Line Item Resource

Pricing

Order Pricing Information

Return Envelope Slip Line

Return Envelope Slip Line Resource

Users

User Resource

Get Current User

HTTP Request

Parameters

Authorization

Teams

Team Resource

Get All Teams

Parameters

Authorization

Get A Specific Team

HTTP Request

Parameters

Authorization

Orders

Orders Resource

Create Order

HTTP Request

Parameters

Authorization

Get Order

HTTP Request

Parameters

Authorization

Get Rate

HTTP Request

Parameters

Authorization

Webhooks

Supported Events

Event Resource

Errors

Errors