API

Goodbits API V1.2


This page outlines details on the V1 API of Goodbits. The API supports the ability to manage your subscribers and content you would like to use.

Goodbits API is based on REST, uses JSON and is authenticated by an authorization token header.

Authentication


To authenticate the API request, an authorization header key 'Authorization' is required. This will authenticate the newsletter and scope the resources available on endpoints to that newsletter.

The API token can be found under your settings for the newsletter.

curl -H "Authorization: your-api-token" https://app.goodbits.io/api/v1/newsletter


GET /api/v1/newsletter


Response - 200 OK

{
  "newsletter": {
    "id": 1234,
    "name": "Newsletter name"
  }
}

POST /api/v1/subscribers


POST Request Data

{
  "subscriber": {
    "email": "valid-email@example.com",
    "first_name": "Mr",
    "last_name": "Nobody"
  }
}

email attribute is required.

Curl example

curl -X POST -H "Content-Type: application/json" -H "Authorization: your-api-token" https://app.goodbits.io/api/v1/subscribers -d '{"subscriber":{"email":"valid-email@example.com","first_name":"Mr","last_name":"Nobody"}}'

Response - 201 Created

{
  "subscriber": {
    "email": "valid-email@example.com",
    "first_name": "Mr",
    "last_name": "Nobody",
    "name": "Mr Nobody"
  }
}

PUT /api/v1/subscribers/:email


Use to change the state of a Subscriber.

PUT Request Data

{
  "subscriber" : {
    "status": "unsubscribed"
  }
}

Other statuses:

cleaned - The subscriber was marked due to a bounce

pending - Awaiting a confirmation (not something you should see with the API)

deleted - Subscriber has been marked as deleted

Response - 200 OK


DELETE /api/v1/subscribers/:email


Will mark a subscriber as deleted. Therefore prenting any future emails being sent to them.

No post data required.

Response - 200 OK


POST /api/v1/links


Create a link (Content) in your Content Library.

POST Request Data

{
  "link" : {
    "url": "http://example.com/article",
    "title": "Article Title",
    "description": "<p>A HTML description of the article</p>",
    "fetch_remote_thumbnail_url": "http://example.com/image-to-be-used-for-thumbnail.jpg",
    "image_candidates": [
      "http://example.com/image-to-be-used-for-thumbnail.jpg",
      "http://example.com/image-to-be-used-for-thumbnail-2.jpg"
    ]
  }
}

Only the url attribute is required.

Thumbnail candidates will be shown in the editor by either those that are set in the created link or by those that are fetched from the URL. But if the image candidates are known they can be created ahead of time.

Response - 201 Created

{
  "link": {
    ...
  }
}

Errors

401 Unauthorized


When an invalid API token is supplied

{
  "errors": "Invalid API Key has been submitted, please refer to your API key under your settings"
}

422 Unprocessable Entity

When there is a missing attribute you will get this error.


GET /api/v1/emails

Parameters

Query Parameters

  • offset (optional): The number of records to skip before starting to return records. Default is 0.
  • limit (optional): The number of records to return. Default is 10.

Request Example

GET /api/v1/emails?offset=0&limit=10

Response

Success Response

Code: 200 OK

Content Example:

{
"emails": [
{
"id": 1,
"subject": "Newsletter Subject 1",
"sent_at": "2023-06-01T12:00:00Z",
"links": {
"self": "/api/v1/emails/1",
"analytics": "/api/v1/emails/1/analytics"
},
"metadata": {
"sort": "sent_at DESC",
"offset": 0,
"limit": 10,
"total_count": 100
}
},
{
"id": 2,
"subject": "Newsletter Subject 2",
"sent_at": "2023-05-25T12:00:00Z",
"links": {
"self": "/api/v1/emails/2",
"analytics": "/api/v1/emails/2/analytics"
},
"metadata": {
"sort": "sent_at DESC",
"offset": 0,
"limit": 10,
"total_count": 100
}
}
// Additional emails...
]
}

Error Response

Code: 404 Not Found

Content Example:

{
"error": "No sent emails found"
}

Response Details

emails

  • Description: An array of sent newsletter emails.
  • Type: Array of objects

emails[n]

  • Description: Details of a single sent newsletter email.
    • id: The ID of the newsletter email.
      • Type: Integer
    • subject: The subject of the newsletter email.
      • Type: String
    • sent_at: The date and time when the newsletter email was sent.
      • Type: String (ISO 8601 format)
    • links: URLs related to the email.
      • self: URL to the email details.
        • Type: String
      • analytics: URL to the email's analytics.
        • Type: String
    • metadata: Metadata about the pagination and sorting.
      • sort: Sorting criteria used.
        • Type: String
      • offset: Offset used in the query.
        • Type: Integer
      • limit: Limit used in the query.
        • Type: Integer
      • total_count: Total number of sent newsletter emails.
        • Type: Integer

Notes

  • The default value for offset is 0 and for limit is 10 if not specified in the request.
  • The response includes metadata to help with pagination.

Error Handling

If no sent emails are found, the endpoint responds with a 404 Not Found status and an error message indicating that no sent emails were found.



GET /api/v1/emails/:newsletter_email_id/analytics

Parameters

URL Parameters

  • newsletter_email_id (required): The ID of the newsletter email for which you want to retrieve analytics.

Response

Success Response

Code: 200 OK

Content Example:

{
"email_id": 123,
"data": {
"recipients": {
"value": 1500,
"delta_previous": 50
},
"unique_opens": {
"value": 1200,
"delta_previous": 100
},
"unique_clicks": {
"value": 300,
"delta_previous": 30
},
"engagement_rate": {
"value": 25.00,
"delta_previous": 2.5
},
"newsletter_links_tracked": [
{
"url": "http://example.com/link1",
"unique_clicks": 100,
"engagement_rate_pct": 33.33
},
{
"url": "http://example.com/link2",
"unique_clicks": 50,
"engagement_rate_pct": 16.67
}
]
},
"links": {
"self": "/api/v1/emails/123/analytics",
"previous_email": "/api/v1/emails/122/analytics"
}
}

Error Response

Code: 404 Not Found

Content Example:

{
"error": "No sent emails found"
}

Response Details

email_id

  • Description: The ID of the current newsletter email.
  • Type: Integer

data

recipients

  • Description: Metrics related to the recipients of the email.
    • value: The number of recipients of the current email.
      • Type: Integer
    • delta_previous: The change in the number of recipients compared to the previous email.
      • Type: Integer

unique_opens

  • Description: Metrics related to unique opens of the email.
    • value: The number of unique opens of the current email.
      • Type: Integer
    • delta_previous: The change in unique opens compared to the previous email.
      • Type: Integer

unique_clicks

  • Description: Metrics related to unique clicks on the email.
    • value: The number of unique clicks on the current email.
      • Type: Integer
    • delta_previous: The change in unique clicks compared to the previous email.
      • Type: Integer

engagement_rate

  • Description: Metrics related to the engagement rate of the email.
    • value: The engagement rate percentage of the current email.
      • Type: Float
    • delta_previous: The change in engagement rate compared to the previous email.
      • Type: Float

newsletter_links_tracked

  • Description: List of links tracked in the email with detailed metrics.
    • url: The URL of the tracked link.
      • Type: String
    • unique_clicks: The number of unique clicks on the link.
      • Type: Integer
    • engagement_rate_pct: The engagement rate percentage for the link.
      • Type: Float

links

  • Description: URLs related to the current and previous email's analytics.
    • self: URL to the current email's analytics.
      • Type: String
    • previous_email: URL to the previous email's analytics if it exists, otherwise null.
      • Type: String or null

Notes

  • The engagement_rate is calculated as the ratio of users who clicked a link to the unique opens of the email, expressed as a percentage.
  • The delta_previous fields provide insights into the change in metrics from the previous email in the series.

Error Handling

If no sent emails are found for the provided newsletter_email_id, the endpoint responds with a 404 Not Found status and an error message indicating that no sent emails were found.



GET /api/v1/subscribers/analytics

Request Example

GET /api/v1/subscribers/analytics

Response

Success Response

Code: 200 OK

{
"total_subscribers": {
"active": 1200,
"unsubscribed": 150,
"deleted": 50
}
}

Error Response

Code: 404 Not Found

{
"error": "Newsletter not found"
}

Response Details

total_subscribers

  • Description: An object containing the counts of subscribers grouped by their status.
  • Type: Object

total_subscribers.status

  • Description: The count of subscribers for each status.
    • active: The number of active subscribers.
      • Type: Integer
    • unsubscribed: The number of unsubscribed subscribers.
      • Type: Integer
    • deleted: The number of deleted subscribers.
      • Type: Integer

Notes

  • The endpoint groups subscribers by their status and returns the total count for each status.
  • The possible statuses are active, unsubscribed, and deleted.

Error Handling

If the specified newsletter is not found, the endpoint responds with a 404 Not Found status and an error message indicating that the newsletter was not found.

Still need help? Contact Us Contact Us