Flodesk API (1.0.0)

Introduction

Flodesk API provides programmatic access to Flodesk data and functionality, allowing developers to integrate and build custom features with your own system.

The REST API communicates exclusively in JSON over SSL (HTTPS). All endpoint URLs begin with https://api.flodesk.com/v1.

Parameters must be serialized in JSON and passed in the request body (not in the query string or form parameters). You should use the media type designation of application/json.

Authentication

Flodesk API supports two types of integrations that use different forms of authentication:

  • Private integrations: Where you (a Flodesk member) or a developer on your behalf, integrate with the API yourself to access and update data for your own Flodesk account. For this type of integration, you’ll authenticate with your personal API key. Learn more about creating and managing API keys here.

  • Partner integrations: You represent an app that would like to build a direct integration which allows customers within your application to authorize direct access to their Flodesk accounts. In this case, you’re acting as an integration partner and must use OAuth2 based authentication with a Client ID and Secret. To apply to build a partner integration, please submit a request using this form.

api_key

Enter the API key as the username and set the password to an empty string. You can create and manage your API keys from the API Key page.

curl "api_endpoint_here" \
-H "User-Agent: Your App Name (www.yourapp.com)" \
-H "Authorization: Basic $(echo YOUR_API_KEY: | base64)"
Security Scheme Type: HTTP
HTTP Authorization Scheme: basic

oauth2

OAuth2 authentication provides developers with a secure way to access Flodesk API data on behalf of other Flodesk users. OAuth2 authentication is used for setting up partner integrations between third-party applications and Flodesk.

curl "api_endpoint_here" \
-H "User-Agent: Your App Name (www.yourapp.com)" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Security Scheme Type: OAuth2
Flow type: authorizationCode
Token URL: https://api.flodesk.com/oauth2/token
Scopes:
  • all -

    full access to all API resources

Oauth2 quick guide

Here's a quick overview of how to get started with OAuth2 based authentication.

  1. After successfully registering your app with Flodesk as outlined above, you can start the Oauth2 flow by redirecting your user to the following url:
https://api.flodesk.com/oauth2/authorize?client_id=<your_client_id>&redirect_uri=<your_redirect_uri>
&response_type=code&state=<a_random_string>
  1. Your user will go through two security steps:
  • Login screen: to authenticate their Flodesk account.
  • Consent screen: to grant permission to your app.
  1. The user will then be redirected back to your app with a verification code that will expire in 30 minutes.

  2. Your app will then need to make a request to exchange that verification code for an access_token and a refresh_token:

curl -X POST "https://api.flodesk.com/oauth2/token" \
  -H "User-Agent: Your App Name (www.yourapp.com)" \
  -H "Authorization: Basic $(echo <your_client_id>:<your_client_secret> | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "code=<verification_code>&redirect_uri=<redirect_uri>&grant_type=authorization_code"
  1. We will authenticate your app and issue the tokens as shown in the example below.
{
  "access_token": "eyJraWQiOiJuUWdsaD...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scopes": "all",
  "refresh_token": "fd_rt_aef123..."
}

You can now use that access_token in the header of your API requests as follows:

Authorization: Bearer <access_token>

UserInfo endpoint

This endpoint can be used to retrieve basic information about the user.

GET https://api.flodesk.com/oauth2/userinfo
Header: "Authorization: Bearer <access_token>"

Example call with curl:

curl https://api.flodesk.com/oauth2/userinfo \
  -H "Authorization: Bearer <access_token>"

Response sample:

{
  "id":"a9c3f01e-6cc4-47c5-8710-e6d3c319888e",
  "email":"foo@baz.com",
  "full_name":"Foo Baz",
  "created_at":"2020-12-24T10:11:42.222Z"
}

Notes on refresh_token

The refresh_token is used to obtain a new access_token when the current one expires without the user's involvement. See the below example of how to perform token refresh:

curl -X POST "https://api.flodesk.com/oauth2/token" \
  -H "User-Agent: Your App Name (www.yourapp.com)" \
  -H "Authorization: Basic $(echo <your_client_id>:<your_client_secret> | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "refresh_token=<your_refresh_token>&grant_type=refresh_token"

Rotation

The refresh_token is a long-lived token and single-use only. Every time a client performs a token refresh, a new refresh_token is issued along with a new access_token, and the previous refresh_token is invalidated.

Make sure you store the new refresh_token for the next refresh.

Rate Limiting

You can make up to 100 requests per minute. If you exceed your rate limit, the API will return a 429 error.

All API requests subject to rate limiting contain information regarding your current rate limit status in the response headers:

HTTP/1.1 200 OK
Status: 200 OK
X-Fd-RateLimit-Limit: 100
X-Fd-RateLimit-Remaining: 68

Subscriber

Subscriber API

List all subscribers.

Authorizations:
api_keyoauth2
query Parameters
page
integer <int64>

The page number. Defaults to 1.

per_page
integer <int64>

The number of records to be returned on each page. Defaults to 20. Maximum 100.

status
string
Enum: "active" "unsubscribed" "unconfirmed" "bounced" "complained" "cleaned"

Optional. The subscriber's status.

active: The subscriber is currently active to receive marketing emails.

unsubscribed: The subscriber has opted out of marketing emails.

unconfirmed: The subscriber is pending for double opt-in confirmation.

bounced: The subscriber's address is undeliverable due to a hard bounce.

complained: The subscriber marked an email as spam.

cleaned: The subscriber was cleaned, learn more here.

segment_id
string

Optional. The segment's id. When included, returns only subscribers who were added to the given segment.

Responses

Response Schema: application/json
object (PaginationRes)
Array of objects (SubscriberRes)

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Create or update a subscriber.

Authorizations:
api_keyoauth2
Request Body schema: */*
id
string

The subscriber's id. Either email or id must be included.

email
string

The subscriber's email. Either email or id must be included.

first_name
string

The subscriber's first name.

last_name
string

The subscriber's last name.

object

An object containing custom field data. E.g. "favorite_color": "Lavender".

segment_ids
Array of strings

The segments this subscriber will be added to. Cap at 50.

double_optin
boolean

Whether or not to require the subscriber to confirm subscription via email.

This option is only available to set with new subscriber creation. Default to false if not indicated.

optin_ip
string

IP address from which the subscriber confirmed their opt-in.

optin_timestamp
string

The date and time the subscribers confirmed their opt-in in ISO 8601 format. E.g. 2023-01-02T15:04:05.999Z.

Responses

Response Schema: application/json
id
string

A read-only generated unique id used to identify each subscriber record.

status
string
Enum: "active" "unsubscribed" "unconfirmed" "bounced" "complained" "cleaned"

The subscriber's status.

active: The subscriber is currently active to receive marketing emails.

unsubscribed: The subscriber has opted out of marketing emails.

unconfirmed: The subscriber is pending for double opt-in confirmation.

bounced: The subscriber's address is undeliverable due to a hard bounce.

complained: The subscriber marked an email as spam.

cleaned: The subscriber was cleaned, learn more here.

email
string

The subscriber's email address.

source
string
Enum: "manual" "csv" "form_optin" "integration" "checkout"

The source from which the subscriber was added to your list.

manual: Added manually.

csv: Via CSV upload.

form_optin: Opted-in via a form.

integration: Added through an integration. E.g. Shopify.

checkout: Opted-in via a Flodesk checkout.

first_name
string

The subscriber's first name.

last_name
string

The subscriber's last name.

Array of objects (SegmentMini)

Segments that the subscriber was added to. Cap at 50.

object

An object containing custom field data. E.g. "favorite_color": "Lavender".

optin_ip
string

IP address from which the subscriber confirmed their opt-in.

optin_timestamp
string <date-time>

The date and time the subscribers confirmed their opt-in in ISO 8601 format. E.g. 2023-01-02T15:04:05.999Z.

created_at
string <date-time>

The date and time the subscriber was added to your list in ISO 8601 format.

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "active",
  • "email": "string",
  • "source": "manual",
  • "first_name": "string",
  • "last_name": "string",
  • "segments": [
    ],
  • "custom_fields": {
    },
  • "optin_ip": "string",
  • "optin_timestamp": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Retrieve a subscriber.

Authorizations:
api_keyoauth2
path Parameters
id_or_email
required
string

Responses

Response Schema: application/json
id
string

A read-only generated unique id used to identify each subscriber record.

status
string
Enum: "active" "unsubscribed" "unconfirmed" "bounced" "complained" "cleaned"

The subscriber's status.

active: The subscriber is currently active to receive marketing emails.

unsubscribed: The subscriber has opted out of marketing emails.

unconfirmed: The subscriber is pending for double opt-in confirmation.

bounced: The subscriber's address is undeliverable due to a hard bounce.

complained: The subscriber marked an email as spam.

cleaned: The subscriber was cleaned, learn more here.

email
string

The subscriber's email address.

source
string
Enum: "manual" "csv" "form_optin" "integration" "checkout"

The source from which the subscriber was added to your list.

manual: Added manually.

csv: Via CSV upload.

form_optin: Opted-in via a form.

integration: Added through an integration. E.g. Shopify.

checkout: Opted-in via a Flodesk checkout.

first_name
string

The subscriber's first name.

last_name
string

The subscriber's last name.

Array of objects (SegmentMini)

Segments that the subscriber was added to. Cap at 50.

object

An object containing custom field data. E.g. "favorite_color": "Lavender".

optin_ip
string

IP address from which the subscriber confirmed their opt-in.

optin_timestamp
string <date-time>

The date and time the subscribers confirmed their opt-in in ISO 8601 format. E.g. 2023-01-02T15:04:05.999Z.

created_at
string <date-time>

The date and time the subscriber was added to your list in ISO 8601 format.

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "active",
  • "email": "string",
  • "source": "manual",
  • "first_name": "string",
  • "last_name": "string",
  • "segments": [
    ],
  • "custom_fields": {
    },
  • "optin_ip": "string",
  • "optin_timestamp": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Remove the subscriber from segments.

Authorizations:
api_keyoauth2
path Parameters
id_or_email
required
string
Request Body schema: */*
segment_ids
required
Array of strings

An array of identifiers of the segments.

Responses

Response Schema: application/json
id
string

A read-only generated unique id used to identify each subscriber record.

status
string
Enum: "active" "unsubscribed" "unconfirmed" "bounced" "complained" "cleaned"

The subscriber's status.

active: The subscriber is currently active to receive marketing emails.

unsubscribed: The subscriber has opted out of marketing emails.

unconfirmed: The subscriber is pending for double opt-in confirmation.

bounced: The subscriber's address is undeliverable due to a hard bounce.

complained: The subscriber marked an email as spam.

cleaned: The subscriber was cleaned, learn more here.

email
string

The subscriber's email address.

source
string
Enum: "manual" "csv" "form_optin" "integration" "checkout"

The source from which the subscriber was added to your list.

manual: Added manually.

csv: Via CSV upload.

form_optin: Opted-in via a form.

integration: Added through an integration. E.g. Shopify.

checkout: Opted-in via a Flodesk checkout.

first_name
string

The subscriber's first name.

last_name
string

The subscriber's last name.

Array of objects (SegmentMini)

Segments that the subscriber was added to. Cap at 50.

object

An object containing custom field data. E.g. "favorite_color": "Lavender".

optin_ip
string

IP address from which the subscriber confirmed their opt-in.

optin_timestamp
string <date-time>

The date and time the subscribers confirmed their opt-in in ISO 8601 format. E.g. 2023-01-02T15:04:05.999Z.

created_at
string <date-time>

The date and time the subscriber was added to your list in ISO 8601 format.

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "active",
  • "email": "string",
  • "source": "manual",
  • "first_name": "string",
  • "last_name": "string",
  • "segments": [
    ],
  • "custom_fields": {
    },
  • "optin_ip": "string",
  • "optin_timestamp": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Add the subscriber to segments.

Authorizations:
api_keyoauth2
path Parameters
id_or_email
required
string
Request Body schema: */*
segment_ids
required
Array of strings

An array of identifiers of the segments.

Responses

Response Schema: application/json
id
string

A read-only generated unique id used to identify each subscriber record.

status
string
Enum: "active" "unsubscribed" "unconfirmed" "bounced" "complained" "cleaned"

The subscriber's status.

active: The subscriber is currently active to receive marketing emails.

unsubscribed: The subscriber has opted out of marketing emails.

unconfirmed: The subscriber is pending for double opt-in confirmation.

bounced: The subscriber's address is undeliverable due to a hard bounce.

complained: The subscriber marked an email as spam.

cleaned: The subscriber was cleaned, learn more here.

email
string

The subscriber's email address.

source
string
Enum: "manual" "csv" "form_optin" "integration" "checkout"

The source from which the subscriber was added to your list.

manual: Added manually.

csv: Via CSV upload.

form_optin: Opted-in via a form.

integration: Added through an integration. E.g. Shopify.

checkout: Opted-in via a Flodesk checkout.

first_name
string

The subscriber's first name.

last_name
string

The subscriber's last name.

Array of objects (SegmentMini)

Segments that the subscriber was added to. Cap at 50.

object

An object containing custom field data. E.g. "favorite_color": "Lavender".

optin_ip
string

IP address from which the subscriber confirmed their opt-in.

optin_timestamp
string <date-time>

The date and time the subscribers confirmed their opt-in in ISO 8601 format. E.g. 2023-01-02T15:04:05.999Z.

created_at
string <date-time>

The date and time the subscriber was added to your list in ISO 8601 format.

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "active",
  • "email": "string",
  • "source": "manual",
  • "first_name": "string",
  • "last_name": "string",
  • "segments": [
    ],
  • "custom_fields": {
    },
  • "optin_ip": "string",
  • "optin_timestamp": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Unsubscribe from all lists.

Authorizations:
api_keyoauth2
path Parameters
id_or_email
required
string

Responses

Response Schema: application/json
id
string

A read-only generated unique id used to identify each subscriber record.

status
string
Enum: "active" "unsubscribed" "unconfirmed" "bounced" "complained" "cleaned"

The subscriber's status.

active: The subscriber is currently active to receive marketing emails.

unsubscribed: The subscriber has opted out of marketing emails.

unconfirmed: The subscriber is pending for double opt-in confirmation.

bounced: The subscriber's address is undeliverable due to a hard bounce.

complained: The subscriber marked an email as spam.

cleaned: The subscriber was cleaned, learn more here.

email
string

The subscriber's email address.

source
string
Enum: "manual" "csv" "form_optin" "integration" "checkout"

The source from which the subscriber was added to your list.

manual: Added manually.

csv: Via CSV upload.

form_optin: Opted-in via a form.

integration: Added through an integration. E.g. Shopify.

checkout: Opted-in via a Flodesk checkout.

first_name
string

The subscriber's first name.

last_name
string

The subscriber's last name.

Array of objects (SegmentMini)

Segments that the subscriber was added to. Cap at 50.

object

An object containing custom field data. E.g. "favorite_color": "Lavender".

optin_ip
string

IP address from which the subscriber confirmed their opt-in.

optin_timestamp
string <date-time>

The date and time the subscribers confirmed their opt-in in ISO 8601 format. E.g. 2023-01-02T15:04:05.999Z.

created_at
string <date-time>

The date and time the subscriber was added to your list in ISO 8601 format.

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "active",
  • "email": "string",
  • "source": "manual",
  • "first_name": "string",
  • "last_name": "string",
  • "segments": [
    ],
  • "custom_fields": {
    },
  • "optin_ip": "string",
  • "optin_timestamp": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Segment

Segment API

List all segments.

Authorizations:
api_keyoauth2
query Parameters
page
integer <int64>

The page number. Defaults to 1.

per_page
integer <int64>

The number of records to be returned on each page. Defaults to 20. Maximum 100.

Responses

Response Schema: application/json
object (PaginationRes)
Array of objects (SegmentRes)

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Create a segment.

Authorizations:
api_keyoauth2
Request Body schema: */*
color
string

The color of the segment using a hex code. Use GET List all segment colors. to view available colors.

name
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "total_active_subscribers": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "color": "string"
}

List all segment colors.

Authorizations:
api_keyoauth2

Responses

Response Schema: application/json
Array
string

Response samples

Content type
application/json
[
  • "string"
]

Retrieve a segment.

Authorizations:
api_keyoauth2
path Parameters
id
required
string

Responses

Response Schema: application/json
id
string

A read-only generated unique id used to identify each segment record.

name
string

Name of the segment.

total_active_subscribers
integer <int64>

The number of active subscribers within the segment.

created_at
string <date-time>

The date and time the segment was created in ISO 8601 format.

color
string

The color of the segment using a hex code. Use GET List all segment colors. to view available colors.

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "total_active_subscribers": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "color": "string"
}

Workflow

Workflow API

List workflows.

Authorizations:
api_keyoauth2
query Parameters
statuses
Array of strings
Items Enum: "active" "paused" "draft"

filter by workflow statuses e.g. statuses=active,paused. Default is all statuses

page
integer <int64>

Default = 1

perPage
integer <int64>

Default = 10

Responses

Response Schema: application/json
Array of objects (WorkflowRes)
object (PaginationRes)

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Add a subscriber to workflow.

Only available for Workflow V2. See upgrade guide.
Note: In order for a subscriber to be added to a workflow subsequent times, (1) the subscriber has to have already completed the workflow, i.e. they cannot currently be active in the workflow, and (2) the "Allow repeat subscribers" setting for the workflow must be toggled on.

Authorizations:
api_keyoauth2
path Parameters
workflow_id
required
string
Request Body schema: */*
email
string

email is required if id is not present

id
string

id is required if email is not present

Responses

Remove a subscriber from workflow.

Only available for Workflow V2. See upgrade guide.

Authorizations:
api_keyoauth2
path Parameters
workflow_id
required
string
id_or_email
required
string

Responses

Custom Field

Custom Field API

List all custom fields (pagination).

Authorizations:
api_keyoauth2
query Parameters
page
integer <int64>

The page number. Defaults to 1.

per_page
integer <int64>

The number of records to be returned on each page. Defaults to 20. Maximum 100.

Responses

Response Schema: application/json
object (PaginationRes)
Array of objects (CustomFieldRes)

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Create a custom field.

Authorizations:
api_keyoauth2
Request Body schema: */*
label
required
string

A friendly display label of the custom field.

Responses

Response samples

Content type
application/json
{
  • "key": "string",
  • "label": "string"
}

List all custom fields.

Authorizations:
api_keyoauth2

Responses

Response Schema: application/json
Array
key
string

The unique identifier of the custom field.

label
string

A friendly display label of the custom field.

Response samples

Content type
application/json
[
  • {
    }
]

Webhook

Webhook API

List all webhooks.

Authorizations:
api_keyoauth2
query Parameters
page
integer <int64>

The page number. Defaults to 1.

per_page
integer <int64>

The number of records to be returned on each page. Defaults to 20. Maximum 100.

Responses

Response Schema: application/json
object (PaginationRes)
Array of objects (WebhookRes)

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Create a webhook.

Authorizations:
api_keyoauth2
Request Body schema: */*
name
required
string

The webhook name.

post_url
required
string

The url that the webhook will post to.

events
required
Array of strings

An array specifying which events are enabled for webhook notifications.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "post_url": "string",
  • "events": [
    ],
  • "created_at": "2019-08-24T14:15:22Z"
}

Delete a webhook.

Authorizations:
api_keyoauth2
path Parameters
id
required
string

Responses

Retrieve a webhook.

Authorizations:
api_keyoauth2
path Parameters
id
required
string

Responses

Response Schema: application/json
id
string

A read-only generated unique id used to identify each webhook record.

post_url
string

The url that the webhook will post to.

events
Array of strings

An array specifying which events are enabled for webhook notifications.

created_at
string <date-time>

The date and time the webhook was created in ISO 8601 format.

Response samples

Content type
application/json
{
  • "id": "string",
  • "post_url": "string",
  • "events": [
    ],
  • "created_at": "2019-08-24T14:15:22Z"
}

Update a webhook.

Authorizations:
api_keyoauth2
path Parameters
id
required
string
Request Body schema: */*
events
Array of strings

An array specifying which events are enabled for webhook notifications.

name
string

The webhook name.

post_url
string

The url that the webhook will post to.

Responses

Response Schema: application/json
id
string

A read-only generated unique id used to identify each webhook record.

post_url
string

The url that the webhook will post to.

events
Array of strings

An array specifying which events are enabled for webhook notifications.

created_at
string <date-time>

The date and time the webhook was created in ISO 8601 format.

Response samples

Content type
application/json
{
  • "id": "string",
  • "post_url": "string",
  • "events": [
    ],
  • "created_at": "2019-08-24T14:15:22Z"
}

Webhook Events

Webhook Events

subscriber.added_to_segment Webhook

This event is triggered when a subscriber is added to a segment in your Flodesk account.

Request Body schema: application/json
event_name
string

The webhook notification's event name. E.g. subscriber.created.

event_time
string <date-time>

The timestamp indicates when the event occurred.

object (SubscriberRes)
object (SegmentMini)
webhook_id
string

The webhook's identifier.

Responses

Request samples

Content type
application/json
{
  • "event_name": "string",
  • "event_time": "2019-08-24T14:15:22Z",
  • "subscriber": {
    },
  • "segment": {
    },
  • "webhook_id": "string"
}

subscriber.created Webhook

This event is triggered when a subscriber is created in your Flodesk account.

Request Body schema: application/json
event_name
string

The webhook notification's event name. E.g. subscriber.created.

event_time
string <date-time>

The timestamp indicates when the event occurred.

object (SubscriberRes)
webhook_id
string

The webhook's identifier.

Responses

Request samples

Content type
application/json
{
  • "event_name": "string",
  • "event_time": "2019-08-24T14:15:22Z",
  • "subscriber": {
    },
  • "webhook_id": "string"
}

subscriber.unsubscribed Webhook

This event is triggered when a subscriber is unsubscribed from all mailings.

Request Body schema: application/json
event_name
string

The webhook notification's event name. E.g. subscriber.created.

event_time
string <date-time>

The timestamp indicates when the event occurred.

object (SubscriberRes)
webhook_id
string

The webhook's identifier.

Responses

Request samples

Content type
application/json
{
  • "event_name": "string",
  • "event_time": "2019-08-24T14:15:22Z",
  • "subscriber": {
    },
  • "webhook_id": "string"
}