API Endpoints

Learn how to use the API to manage your subscribers.

post
Add subscriber

https://letterdrop.com/api/v1/subscriber/add
Add a subscriber to your publication.
Request
Response
Request
Headers
api-key
required
string
API key that is unique to your publication
Body Parameters
additionalData
optional
object
An object of additional fields to associate with this subscriber. See below for accepted fields.
welcomeEmail
optional
boolean
Whether the subscriber should receive a welcome email
type
required
string
Whether the subscriber is on a free or paid plan
email
required
string
Email of the subscriber to be added
Response
200: OK
Subscriber added
{
success: "true",
type: "free",
publication: "my-publication-domain",
message: "Subscriber added"
}
400: Bad Request
Invalid inputs
{
success: "false",
message: "Invalid subscriber"
}

Accepted fields for additionalData object

Field Name

Type

Description

name

string

Name of subscriber

location

string

Location of the subscriber

title

string

Job title of the subscriber

companyName

string

Name of the company subscriber is employed at

companySize

number

Number of employees at company the subscriber is employed at

industry

string

Industry the subscriber is in

twitter

string

URL of Twitter profile for subscriber

twitterFollowers

number

Number of Twitter followers of subscriber

linkedin

string

URL of LinkedIn profile for subscriber

github

string

URL of GitHub profile for subscriber

facebook

string

URL of Facebook profile for subscriber

A sample object looks like this:

additionalData: {
name: "Sundar Pichai",
location: "Mountain View, CA",
twitter: "https://twitter.com/sundarpichai",
twitterFollowers: 3300000,
company: "Google,
companySize: 120000,
industry: "Internet",
linkedin: "https://www.linkedin.com/in/sundarpichai"
}

If you want to add your own custom fields and data, just create the fields in Letterdrop and then add the data in additionalData. For example, if you created a custom field Downloaded Whitepaper, you could pass a value for it like so:

additionalData: {
name: "Sundar Pichai",
location: "Mountain View, CA",
twitter: "https://twitter.com/sundarpichai",
twitterFollowers: 3300000,
company: "Google,
companySize: 120000,
industry: "Internet",
linkedin: "https://www.linkedin.com/in/sundarpichai",
"Downloaded Whitepaper": true
}

get
Add subscriber

https://letterdrop.com/api/v1/:domain/subscribe
Add a subscriber to your publication without an API key. Use this in places where you can only send a GET request.
Request
Response
Request
Path Parameters
domain
required
string
Your publication domain. The domain in {domain}.letterdrop.com
Query Parameters
email
required
string
Email of the subscriber to be added
Response
200: OK
Subscriber added
{
message: "Subscribed!"
}
400: Bad Request
Invalid inputs
{
message: "Error"
}

post
Add subscriber through form

https://letterdrop.com/api/v1/subscriber/add/:domain
Add a subscriber to your publication without an API key. Use this in places like Webflow forms.
Request
Response
Request
Path Parameters
domain
required
string
Your publication domain. The domain in {domain}.letterdrop.com
Body Parameters
email
required
string
Email of the subscriber to be added
Response
200: OK
Subscriber added
{
message: "Subscribed!"
}
400: Bad Request
Invalid inputs
{
message: "Error"
}

post
Remove Subscriber

https://letterdrop.com/api/v1/subscriber/remove
Remove a subscriber from your publication.
Request
Response
Request
Headers
api-key
required
string
API key that is unique to your publication
Query Parameters
email
required
string
Email of the subscriber to be removed
Response
200: OK
Subscriber removed
{
success: true,
email: email,
publication: "my-publication-domain",
message: "Subscriber removed"
}
400: Bad Request
Invalid inputs
{
success: false,
message: "Invalid email"
}

post
List posts

https://letterdrop.com/api/v1/posts
Get a summary of all your posts to be displayed on your home page. The API is paginated. Start with offset: 0 and a fixed small value for limit. We recommend 5. Then you can query again, but this time, increment the offset to 5 to get the next 5 posts. You can check if there are most posts to query by checking hasNextPage in the response is true.
Request
Response
Request
Headers
api-key
required
string
API key that is unique to your publication
Body Parameters
query
optional
string
Search for posts containing these words
offset
required
number
Index of first post to return
limit
required
number
Number of posts to return
Response
200: OK
The response tells you the current page, whether there is more data, the total number of posts and an array of posts you queried.
{
success: true,
page: 0,
hasNextPage: true,
totalPosts: 20,
posts: [
{
title: "My great post",
subtitle: "It really is great, I promise",
text: "This is the body of my post in plain text with only line breaks denoted by \n",
readTime: "3 min read",
wordCount: 565,
publishedOn: "2020-11-21T00:08:45.348Z",
isPrivate: false,
type: "free"
url: "this-is-a-great-post"
coverImage: "https://coverphoto.jpg"
},
...
]
}
400: Bad Request
{
success: false,
message: "Invalid params"
}

post
Get post

https://letterdrop.com/api/v1/post/get/:{id}
Get a single post. Here, id is adapt-your-writing-to-the-medium in https://letterdrop.com/@wheres-my-audience/adapt-your-writing-to-the-medium for example.
Request
Response
Request
Path Parameters
id
required
string
The url value from a post of interest in /posts
Headers
api-key
required
string
API key that is unique to your publication
Response
200: OK
Full details on a post.
{
success: true,
title: "My great post",
subtitle: "It really is great, I promise",
text: "<html><p>This is the body of my post in HTML<p></html>",
readTime: "3 min read",
wordCount: 565,
publishedOn: "2020-11-21T00:08:45.348Z",
isPrivate: false,
type: "free"
url: "this-is-a-great-post"
shareLink: {
thumbnail: "https://thumbnail.jpg",
description: "My great post"
},
coverImage: "https://coverphoto.jpg"
}
400: Bad Request
{
success: false,
message: "Couldn't find post"
}

post
Draft post

https://letterdrop.com/api/v1/post/draft
Draft a post.
Request
Response
Request
Headers
api-key
required
string
API key that is unique to your publication
Body Parameters
html
required
string
Body of your post in HTML format
subtitle
optional
string
Subtitle of your post
title
required
string
Title of your post
Response
200: OK
Link to post draft
{
success: true,
draftLink: "https://app.letterdrop.com/post/6049755c5392b01d67ffd8cf"
}
400: Bad Request
{
success: false,
message: "title can't be empty"
}