API Overview

The MailLift API makes it easy to send and manage an unlimited quantity of handwritten letters.

Each letter item in MailLift represents a single shippable letter with recipient address, return address (optional), and message body. You can access each letter using the letter's unique ID to modify the letter in many steps of the process.

Address Formatting

The MailLift v2 API supports free-form addresses for the Sender and the Recipient. Simply enter the addresses as you would in a textarea field with new line caracters (\n) separating lines in the address. International postage rates may apply to letters addressed outside of the US.

Letter Statuses
Status CodeDescription
newLetter has been queued
assignedLetter is assigned to a handwriter
writingA handwriter is currently writing the letter
pendingQcApprovalThe handwriter has finished and we are reviewing the letter
approvedThe letter has passed all quality checks and is ready to go in the mail
inMailThe letter is in the mail
modifiedPendingRewriteScheduleThe letter object was modified after being written and needs to be re-written
qcRejectedPendingRewriteThe letter object failed quality checks and is being rewritten
canceledThe letter is canceled and will not be sent
Billing

The first 50 words are included in the price of a letter. After that, each additional word is $0.0249 per word. The final cost is rounded up to the nearest penny.

Each letter is added to your montly bill when the letter is created with the API. Your credit card is charged at the end of each month with the total amount of letters and any billable revisions or cancellations.

Any letter with the status of new or assigned (with no previous revisions) can be modified or canceled free of charge.

The first few revisions and cancellations are completely free of charge (we even refund canceled messages). If your account reaches the limit of free revisions and cancellations, we may charge for re-writes.

To avoid extra charges, make sure you edit or cancel a letter before it moves to the writing phase.

If you have any quesitons or concerns, contact support@maillift.com.




Create a new letter

Create a new letter in one post. Each letter is billed to your invoice at the time of posting. The output includes the letter ID and the billed price of the letter.

Recipient
required
Use line breaks (\n character) to separate lines in the field
Brian Curliss
321 Main St.
#102
Houston, TX 76853
Sender
optional
Same format as Recipient (free form, use \n for line breaks)
MessageBody
required
e.g. "Testing out this sweet handwritten letter API."
ScheduledDelivery
optional
Date in the future of the format YYYY-MM-DD
Notes
optional
Sepcify additional notes for our writers (e.g. "female handwriting, cursive"). If nothing is specified, we will use our standard stationery and select an optimal writing style for your letter. If the request specifies something outside of our normal stationery (e.g. "add my business card with this letter"), we may contact you to make arrangements if we haven't already.
POST https://api.maillift.com/2016-04-21/letter/
Sample request
Use %0A to URL encode a newline character with curl.
$ curl https://api.maillift.com/2016-04-21/letter \
-u {username}:{apikey} \
-d $"Recipient=Brian Curliss%0A321 Main St.%0A#102%0AHouston, TX 76853" \
-d "MessageBody=Testing out this sweet handwritten letter API."
-d "Notes=female print handwriting"
Sample response
200 OK
 {
   "Uuid":"9cd3a95b-0846-11e3-a194-060f0679ee2c",
   "Owner":"daniel@maillift.com",
   "Sender": "",
   "Recipient":"Brian Curliss\n321 Main St.\n#102\nHouston, TX 76853",
   "MessageBody":"Testing out this sweet handwritten letter API.",
   "ScheduledDelivery":"2016-12-22",
   "ApprovalRequired":"false",
   "Status":"assigned",
   "Pictures":[]
  }
	        		

List all letters

Gets a list of letters created by the account. List is ordered by send date descending (this includes letters that have and have not been sent)

CreationDate
optional
Get letters created on (=yyyy-mm-dd), before (<=yyyy-mm-dd) or after (>=yyyy-mm-dd) the specified date (also between two dates <=yyyy-mm-dd,>=yyyy-mm-dd).
Status
optional
Get letters of the specified status
GET https://api.maillift.com/2016-04-21/letter/?{refining parameters}
Sample request
$ curl https://api.maillift.com/2016-04-21/letter
-u {username}:{apikey}
Sample response
200 OK
[
 {
   "Uuid":"9cd3a95b-0846-11e3-a194-060f0679ee2c",
   "Owner":"daniel@maillift.com",
   "Sender": "",
   "Recipient":"Brian Curliss\n321 Main St.\n#102\nHouston, TX 76853",
   "MessageBody":"Testing out this sweet handwritten letter API.",
   "ScheduledDelivery":"2016-12-23",
   "ApprovalRequired":"false",
   "Status":"assigned",
   "Pictures":[
    "1" : [
     {
      "version": "1",
   	  "url": "https://api.maillift.com/..."
     },
     ...
    ]
   ]
  },
  ...
]			

Get single letter

Returns a single letter object matching the letter ID provided.

GET https://api.maillift.com/2016-04-21/letter/{Uuid}
Sample request
$ curl https://api.maillift.com/2016-04-21/letter/{Uuid}
-u {username}:{apikey}
Sample response
200 OK
{
 "Uuid":"9cd3a95b-0846-11e3-a194-060f0679ee2c",
 "Owner":"daniel@maillift.com",
 "Sender": "",
 "Recipient":"Brian Curliss\n321 Main St.\n#102\nHouston, TX 76853",
 "MessageBody":"Testing out this sweet handwritten letter API.",
 "ScheduledDelivery":"2016-12-23",
 "ApprovalRequired":"false",
 "Status":"assigned",
 "Pictures":[
    "1" : [
     {
      "version": "1",
   	  "url": "https://api.maillift.com/..."
     },
     ...
    ]
   ]
}
					

Modify an existing letter

The letter being modified must have a delivery date in the future and must not be past a certain point in the process. Modifying a letter may change the status of a letter or the delivery date.

MessageBody
ScheduledDelivery
ApprovalRequired
PUT https://api.maillift.com/2016-04-21/letter/{Uuid}
Sample request
$ curl https://api.maillift.com/2016-04-21/letter/{Uuid} \ 
-u {username}:{apikey} \
-d "MessageBody=This is the new body"
Sample response
202 Accepted
 {
   "Uuid":"9cd3a95b-0846-11e3-a194-060f0679ee2c",
   "Owner":"daniel@maillift.com",
   "Sender": "",
   "Recipient":"Brian Curliss\n321 Main St.\n#102\nHouston, TX 76853",
   "MessageBody":"This is the new body",
   "ScheduledDelivery":"2016-12-23",
   "ApprovalRequired":"false",
   "Status":"assigned",
   "Pictures":[]
  }

	        		

Cancel sending a letter

The letter being canceled must not be past the "In Mail" point in the MailLift process.

Notes
optional
e.g. "We don't need to send this letter"
Delete https://api.maillift.com/2016-04-21/letter/{Uuid}
Sample request
$ curl https://api.maillift.com/2016-04-21/letter/{Uuid} \ 
-u {username}:{apikey} \
-d "Notes=We decided not to send this letter"
Sample response
200 OK
{
    "RefundAmount": 8.29
}
	        		

List status history for a letter

Gets a full list of statuses associated with the letter identified by the specified letter ID. The list is sorted in order from the most recent status message.

get https://api.maillift.com/2016-04-21/letter/status/{Uuid}
Sample request
$ curl https://api.maillift.com/2016-04-21/letter/status/{Uuid} \ 
-u {username}:{apikey}
Sample response
200 OK
[
 {
  "StatusCode": "assigned",
  "StatusDate": "2016-04-23 01:43:07",
  "StatusNotes": "Assigning letter to 56 (by: 56)"
 },
 {
  "StatusCode": "new",
  "StatusDate": "2016-04-23 01:42:17",
  "StatusNotes": "Letter created by API. (daniel@maillift.com)"
 }
]