Getting Started

Welcome to the official BirdSend API documentation. Our RESTful API lets your app to manage contacts, create and send emails, set up automation, and many more. The best thing is that you can use the programming language that you already know and love.

Let's Build Your App

---

BirdSend API platform includes numerous resource-oriented endpoints to help you enrich your app. API responses will be returned in JSON, and all parameters passed to the request body must be formatted in JSON. Our API uses HTTP response codes to indicate errors.

Base API URL

Below is the base API URL or the root endpoint:

https://api.birdsend.co/v1

For example, API request endpoint to obtain the list of contacts is /contacts so the full URL for the request will be https://api.birdsend.co/v1/contacts.

The version part of the base API URL above (v1 in this case) indicates the current version of our API. In the future, if we increment the version, the version part of the base URL will be changed too (e.g. https://api.birdsend.co/v2).

NOTE: Future API updates will be backwards compatible for a specific amount of time (e.g. months) to give you time to migrate to the new API version.

Create and Manage API Applications

Please login to the BirdSend developer area to register your first application or manage/edit your existing applications. If you don't have a BirdSend user account, you can sign up for the developer account here.

NOTE: If you're an existing BirdSend User, you don't need to create a developer account but you can login to your exisiting BirdSend account, and go to Settings > API Integration

Throttling and Rate Limiting

---

To ensure a great experience for all our users and developers, we have to limit the API connection requests. Each account is permitted up to 5 requests per second. If you exceed your rate limit, the API will return a 429 Too Many Requests HTTP response code.

Please review our Best Practices section to make sure your integration with BirdSend API is as reliable as possible.

Authentication

For private apps or personal use, you can use the “Personal Access Token” that you can manually generate after creating an app in the developer area

For public apps, you can use the OAuth authentication flow.

Register Your Application

---

Before you can register your application, you need to have a BirdSend user account or a developer account. Opening a developer account is free and you can do so by clicking here

1. Go to BirdSend developer area here.
2. Click the “Create New App” button on the top right.
3. Fill in the application registration form, and click the “Create Your Application” button.
4. Once created, your application will have the Client ID and Secret keys, and also the Personal Access Token. Do NOT share those keys and keep the information secret.

Using The Personal Access Token

---

Authenticating using the personal access token is very simple. After you’ve manually generated the personal access token, simply add the authentication header when making an API call as below:

Authorization: “Bearer {your_personal_access_token}”

Using The OAuth Flow

---

First, get authorization from the user by redirecting them to the URL below:

https://app.birdsend.co/oauth/authorize?response_type=code&client_id={client_id}&redirect_uri={callback_url}&scope={scopes}
                

• {client_id} - Change this with your application’s client id.
• {callback_url} - Change this with the URL where you want to redirect the users after they authorize your application. The full URL specified here must be identical to the callback URL that you set up in your application.
• {scopes} - (Optional) change this with a scope name. For example: write.

Once the user has authorized your application, BirdSend will redirect the user to the callback URL you provided. An Authorization Code will be appended to your callback URL in a query string named code.

Get the value of the authorization code, and then convert it to an Access Token by making a POST request to BirdSend.

Example using curl:

curl --request POST \
                  --url 'https://app.birdsend.co/oauth/token' \
                  --data 'grant_type=authorization_code
                    &client_id={client_id}
                    &client_secret={client_secret}
                    &redirect_uri={callback_url}
                    &code={authorization_code}'
                

Example response:

            {
              "token_type": "Bearer",
              "expires_in": 5184000,
              "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImUwNTZkN...",
              "refresh_token": "def50200ed83c45b0c66cc8f92d763a1d26a26..."
            }
                

Now you can use the retrieved access token to authenticate your API requests to BirdSend. In every request, simply add an authorization header as below:

Authorization: “Bearer {access_token}”

Refresh Access Token

The access token will expire in 60 days after created. You need to save the refresh_token value to issue the refresh access token once it's expired or when you get a 401 Unauthenticated response from BirdSend API server.

To issue refresh access token you can make a POST request to BirdSend like example below:

curl --request POST \
                  --url 'https://app.birdsend.co/oauth/token' \
                  --data 'grant_type=refresh_token
                    &refresh_token={refresh_token}
                    &client_id={client_id}
                    &client_secret={client_secret}
                    &scope={scopes}'
                

Basic Usage

Accepted HTTP Methods

---

• GET - Use this method to retrieve or read the data from our API. You can use this to retrieve a list collection of data or single row data (scope: read).
• POST - Use this method to create new resources. For example, if you want to add a new contact, you can pass the contact data in the post request body make the request to the contact endpoint (scope: write).
• PATCH - Use this method to update an existing resource. For example, if you want to update a contact data, you can pass the updated data in the request body and make the request to the correct endpoint (scope: write).
• DELETE - Use this method to delete or remove existing a resource (scope: write).

Request Headers

---

• Authorization: Bearer {access_token}
• Content-Type: application/json
• Accept: application/json

Pagination

---

All list collection data responses from our API are paginated. Pagination links and metadata are included along with the response. Example:

                
            "data": {
              ...
            },
            "links": {
              "first": "https://api.birdsend.co/v1/sequences?page=1",
              "last": "https://api.birdsend.co/v1/sequences?page=20",
              "prev": null,
              "next": 2
            },
            "meta": {
              "current_page": 1,
              "from": 1,
              "to": 10,
              "last_page": 20,
              "path": "https://api.birdsend.co/v1/sequences",
              "per_page": 10
              "total": 20
            }
                
               

Using Parameters

---

BirdSend API allows you to customize the returned response data by using parameters that you can append into the endpoint URL as query strings.

Let say that you want to show 50 contacts data from page 3, then you can add the parameters into the contacts endpoint (/contacts) like below

https://api.birdsend.co/v1/contacts?page=3&per_page=50

You can also sort the return data by making a request to:

https://api.birdsend.co/v1/contacts?page=3&per_page=50&order_by=email&sort=desc

The parameters can also be used for returning specific data only. Here’s an example:

https://api.birdsend.co/v1/contacts?per_page=20&search_by=email&keyword={keyword_here}

Errors

BirdSend uses HTTP response code to indicate success or failure of an API request. BirdSend will return response code in the range of 2xx for every successful request. It’s usually code 201 for a successful new resource creation request, 204 for resource deletion request and 200 for another type of requests.

Codes in the 4xx range mean there’s something wrong or error with the request (e.g. invalid request data type, unauthorized request, required data is missing, etc), while codes in the 5xx range indicate an error with the BirdSend’s servers.

For most error response codes in the 4xx range, BirdSend will also include detail error message as the response body in a human-readable JSON format.

If your application receives the 5xx error code, then please contact our support.

HTTP Response Code Summary

Best Practice

We understand that implementation of any API, including the BirdSend API, vary from business to business. The cost of using the BirdSend API is free and we welcome developers from around the world to use our API.

To ensure and maintain a great experience for all our users, we will be closely monitoring your API usage. Even a badly written small application may give our system an unnecessary burden, thus affecting other users. In order to make sure that your app integration is as reliable as possible, please review the best practices below

Always Make Smart Requests

---

Make sure that your application is making a call only when necessary. Too many unnecessary API calls in less than one minute (or too many simultaneous requests) will slow down the response time and potentially impacts system performance.

When your app frequently impacts our system performance, you may receive unwanted attention from our team and we may block your API requests.

Always Cache The Data

We strongly recommend that you cache the response data that you receive from our API, especially the frequently-used data that don’t change often. You can also cache data that change often by using a shorter cache expiration (e.g. 5 minutes).

Avoid Unnecessary Repeated Requests

Updating a resource with the same data is unnecessary so you want to avoid a call like this. You can check your local data (e.g. cache; see above) first to see if your app really needs to make a change. If it turns out that you don’t need to make any change, then you can avoid making an unnecessary change. Reducing requests to our API also helps your application to avoid getting throttled and limited.

Properly Handle Errors

Keep in mind that errors and exceptions will sometimes happen. Validating the request data first before making a call to our API to avoid unwanted results is a good practice. Use sound programming practices to handle the error responses returning by our API. See the Errors section above.

Properly Handle The Limits

When your application receives the 429 Too Many Requests error response, it's a good idea to pause all API calls for the hour and continue making requests in the next hour. In order to avoid getting limited, please try to make fewer calls.