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

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