NAV Navbar
Logo

Introduction

API Endpoint
https://your_domain.betasend.com/api/v1/

Welcome to the Betasend API!
You can use our API to access our API endpoints, which can get information on subscribers and lists.

You can view code examples in the dark area to the right.

Replace YOUR_API_KEY and YOUR_HASH_KEY in code examples with API key and Hash which you can find them on your account profile page.

Account

Retrieve Account Information

curl "https://your_domain.betasend.com/api/v1/account-details"
 -d 'api=YOUR_API_KEY&hash=YOUR_HASH_KEY'

Following shows response object:

[
  {
     "user_id": 10,
    "domain": "your_domain_name",
    "email": "your_email@email.com",
    "first_name": "first_name",
    "last_name": "last_name",
    "user_code": "333333",
    "mailer_settings": "Enabled",
    "reputation": "Trusted"
  }
]

Retrieves account information.

HTTP Request

POST /api/v1/account-details

Query Parameters

Parameter Description
api Your API key
hash Your Hash key

Update Account Information

curl "https://your_domain.betasend.com/api/v1/account-update"
 -d 'api=YOUR_API_KEY&hash=YOUR_HASH_KEY&first_name=Sean&last_name=S&email=your_email@email.com&city=Your City'

Following shows response object:

{
  "success": "Your contact info has been updated."
}

Updates account information.

HTTP Request

POST /api/v1/account-update

Query Parameters

Parameter Description
api Your API key
hash Your Hash key
email Email address
first_name First name
last_name Last name
company Company
address Address
city City
zipcode Zip code
country Country
state State
phone Phone number

Subscribers

Add Subscriber

curl "https://your_domain.betasend.com/api/v1/subscribers-add"
 -d 'api=YOUR_API_KEY&hash=YOUR_HASH_KEY&email=subscriber01@gmail.com&list_id=1,2'

Following shows response object:

{
  "success": "Subscriber added successfully"
}

Following shows response object for list id which is not existing: json { "error": { "406": "Not Acceptable", "messages": "Invalid list id : 10" } }

Subscribes an email address to multiple lists.

HTTP Request

POST /api/v1/subscribers-add

Query Parameters

Parameter Description
api Your API key
hash Your Hash key
email Email address to subscribe
list_id Comma-separated ids of lists
first_name Subscriber’s first name
last_name Subscriber’s last name

Retrieve Subscribers Information

curl "https://your_domain.betasend.com/api/v1/subscribers-details"
 -d 'api=YOUR_API_KEY&hash=YOUR_HASH_KEY&email=subscriber01@gmail.com,subscriber02@gmail.com,noexist@gmail.com'

Following shows response object:

{
  "subscriber01@gmail.com": {
    "general_info": [
      {
        "subscribed": "No",
        "subscribed-date": "30-11--0001 00:00:00",
        "unsubscribed-date": "31-12-1969 19:00:00"
      }
    ],
    "list_info": [
      {
        "list-id": 3,
        "list-name": "Empty List",
        "subscribed": "No",
        "subscribed-date": "15-02-2017 03:54:01"
      },
      {
        "list-id": 4,
        "list-name": "List Create Test",
        "subscribed": "No",
        "subscribed-date": "15-02-2017 03:55:11"
      }
    ]
  },
  "webformtest01@gmail.com": {
    "general_info": [
      {
        "subscribed": "Yes",
        "subscribed-date": "11-01-2017 23:47:01"
      }
    ],
    "list_info": [
      {
        "list-id": 1,
        "list-name": "First List",
        "subscribed": "No",
        "subscribed-date": "12-01-2017 07:47:01",
        "unsubscribed-date": "14-01-2017 04:26:02"
      }
    ]
  },
  "noexsit@gmail.com": {
    "error_info": [
      {
        "message": "Email not subscribed"
      }
    ]
  }
}

Retrieves subscribers’ information.

HTTP Request

POST /api/v1/subscribers-details

Query Parameters

Parameter Description
api Your API key
hash Your Hash key
email List of email addresses

Unsubscribe Subscriber

curl "https://your_domain.betasend.com/api/v1/subscribers-remove"
 -d 'api=YOUR_API_KEY&hash=YOUR_HASH_KEY&email=subscriber01@gmail.com&list_id=1'

Following shows response object:

{
  "success": "Unsubscribed Successfully"
}

Following shows response object for email address which is not existing or unsubscribed:

{
  "error": {
    "406": "Not Acceptable",
    "messages": "Subscriber not available in this list"
  }
}

Unsubscribes Subscriber from list.

HTTP Request

POST /api/v1/subscribers-remove

Query Parameters

Parameter Description
api Your API key
hash Your Hash key
email Email address to subscribe
list_id List id

Delete Subscriber

curl "https://your_domain.betasend.com/api/v1/subscribers-delete"
 -d 'api=YOUR_API_KEY&hash=YOUR_HASH_KEY&email=subscriber01@gmail.com&list_id=1,2'

Following shows response object:

{
  "success": "Deleted subscriber successfully"
}

Following shows response object for email address which is not existing or unsubscribed:

{
  "error": {
    "406": "Not Acceptable",
    "messages": "Subscriber not available in this account"
  }
}

Following shows response object for list id which are not existing:

{
  "error": {
    "406": "Not Acceptable",
    "messages": "Subscriber not available in this list : 3"
  }
}

Deletes subscriber from multiple lists.

HTTP Request

POST /api/v1/subscribers-delete

Query Parameters

Parameter Description
api Your API key
hash Your Hash key
email Email address to subscribe
list_id Comma-separated ids of lists

Email Verification

Verify Reply Email

curl "https://your_domain.betasend.com/api/v1/verify-reply-email"
 -d 'api=YOUR_API_KEY&hash=YOUR_HASH_KEY&email=myfromemail01@gmail.com'

Following shows response object:

{
  "success": "Verification Code was sent, Please Check your mail"
}

Sends verification code by email address to verify email.

HTTP Request

POST /api/v1/verify-reply-email

Query Parameters

Parameter Description
api Your API key
hash Your Hash key
email Email address to verify

Verify Reply Email Code

curl "https://your_domain.betasend.com/api/v1/verify-reply-email-code"
 -d 'api=YOUR_API_KEY&hash=YOUR_HASH_KEY&verification_code=axz3weqd390'

Following shows response object:

{
  "success": "Verified code successfully"
}

Verifies email address by checking verification code

HTTP Request

POST /api/v1/verify-reply-email-code

Query Parameters

Parameter Description
api Your API key
hash Your Hash key
verification_code Verification code

Lists

Create List

curl "https://your_domain.betasend.com/api/v1/list-create"
 -d 'api=YOUR_API_KEY&hash=YOUR_HASH_KEY&list_name=List1&from_name=Sean&reply_email=seans@gmail.com&company=Company1&address=Address1&city=City1&zipcode=33333&country=US&state=California'

Following shows response object:

{
  "success": "List added successfully",
  "list_id": 5
}

Creates a new list.

HTTP Request

POST /api/v1/list-create

Query Parameters

Parameter Description
api Your API key
hash Your Hash key
list_name List name
from_name From name
reply_email From email address
company Company name
address Address
city City name
zipcode Postal code
country Country name
state State name

Update List

curl "https://your_domain.betasend.com/api/v1/list-update"
 -d 'api=YOUR_API_KEY&hash=YOUR_HASH_KEY&list_id=5&list_name=List1&from_name=Sean&reply_email=seans@gmail.com&company=Company1&address=Address1&city=City1&zipcode=33333&country=US&state=California'

Following shows response object:

{
  "success": "Lists updated successfully"
}

Following shows response object for list id which is not existing:

{
  "error": {
    "406": "Not Acceptable",
    "messages": "Invalid list id"
  }
}

Updates list information.

HTTP Request

POST /api/v1/list-update

Query Parameters

Parameter Description
api Your API key
hash Your Hash key
list_id List id
list_name List name
from_name From name
reply_email From email address
company Company name
address Address
city City name
zipcode Postal code
country Country name
state State name

Delete List

curl "https://your_domain.betasend.com/api/v1/list-delete"
 -d 'api=YOUR_API_KEY&hash=YOUR_HASH_KEY&list_id=5'

Following shows response object:

{
  "success": "List deleted successfully"
}

Following shows response object for list id which is not existing:

{
  "error": {
    "406": "Not Acceptable",
    "messages": "Invalid list id : 10"
  }
}

Deletes a list.

HTTP Request

POST /api/v1/list-delete

Query Parameters

Parameter Description
api Your API key
hash Your Hash key
list_id List id

Retrieve Lists

curl "https://your_domain.betasend.com/api/v1/lists"
 -d 'api=YOUR_API_KEY&hash=YOUR_HASH_KEY&list_id=5&start=1&limit=10'

Following shows response object when list_id=5:

[
  {
    "list_id": 5,
    "list_name": "List1",
    "default_from_name": "Sean",
    "default_from_email": "seans@gmail.com",
    "default_reply_email": "",
    "default_subject": "",
    "list_key": "HnpCVJkQ9r",
    "description": "",
    "created_by": "Sean S",
    "contact_name": "",
    "contact_email": "",
    "company": "Company1",
    "address": "My Address",
    "city": "My City",
    "postal_code": "33333",
    "country": "Bangladesh",
    "state_code": "My State Code",
    "phone": "123456789",
    "status": "Active",
    "date_added": "2017-02-20 07:09:03",
    "deleted_date": "0000-00-00 00:00:00"
  }
]

Following shows response object for empty list_id:

[
  {
    "list_id": 1,
    "list_name": "First List",
    "default_from_name": "First List",
    "default_from_email": "myfrom@gmail.com",
    "default_reply_email": "",
    "default_subject": "First List",
    "list_key": "ZdkvDNn7jH",
    "description": "",
    "created_by": "Sean S",
    "contact_name": "",
    "contact_email": "",
    "company": "Company1",
    "address": "My Address",
    "city": "My City",
    "postal_code": "33333",
    "country": "Bangladesh",
    "state_code": "My State Code",
    "phone": "123456789",
    "status": "Active",
    "date_added": "2017-01-11 21:59:16",
    "deleted_date": "0000-00-00 00:00:00"
  },
  {
    "list_id": 5,
    "list_name": "List1",
    "default_from_name": "Sean",
    "default_from_email": "seans@gmail.com",
    "default_reply_email": "",
    "default_subject": "",
    "list_key": "HnpCVJkQ9r",
    "description": "",
    "created_by": "Sean S",
    "contact_name": "",
    "contact_email": "",
    "company": "Company1",
    "address": "My Address",
    "city": "My City",
    "postal_code": "33333",
    "country": "Bangladesh",
    "state_code": "My State Code",
    "phone": "123456789",
    "status": "Active",
    "date_added": "2017-02-20 07:09:03",
    "deleted_date": "0000-00-00 00:00:00"
  }
]

Retrieves lists information.

If you wish to retrieve all account lists then simply don’t give any value to list_id and leave it blank.

HTTP Request

POST /api/v1/lists

Query Parameters

Parameter Description
api Your API key
hash Your Hash key
list_id List id (used to retrieve information of a specific list)
start Starting offset from which searching will be performed (default is 1)
limit Maximum count of subscribers returned (default is 10)

Retrieve List Statistics

curl "https://your_domain.betasend.com/api/v1/list-statistics"
 -d 'api=YOUR_API_KEY&hash=YOUR_HASH_KEY&list_id=5'

Following shows response object:

{
  "1": {
    "list_name": "First List",
    "total-emails": 7,
    "subscribed-emails": 4,
    "unsubscribed-emails": 3,
    "click-rate": "2%",
    "open-rate": "0%"
  }
}

Retrieves statistics of a list.

HTTP Request

POST /api/v1/list-statistics

Query Parameters

Parameter Description
api Your API key
hash Your Hash key
list_id List id

Add Subscribers

curl "https://your_domain.betasend.com/api/v1/list-subscribers-add"
 -d 'api=YOUR_API_KEY&hash=YOUR_HASH_KEY&email=subscriber01@gmail.com,subscriber02@gmail.com&list_id=5'

Following shows response object:

{
  "success": "Subscriber added successfully"
}

Following shows response object for list id which is not existing: json { "error": { "406": "Not Acceptable", "messages": "Invalid list id : 10" } }

Subscribes multiple email addresses to a list.

HTTP Request

POST /api/v1/list-subscribers-add

Query Parameters

Parameter Description
api Your API key
hash Your Hash key
email Comma-separated email addresses
list_id List id

Retrieve Subscribers

curl "https://your_domain.betasend.com/api/v1/list-subscribers"
 -d 'api=YOUR_API_KEY&hash=YOUR_HASH_KEY&list_id=1&start=1&limit=10'

Following shows response object for list_id provided:

[
  {
    "subscribe_id": 16,
    "subscribed": "Yes",
    "email": "webformtest010@gmail.com",
    "first_name": "WebForm",
    "last_name": "Test01",
    "subscribed_date": "2017-01-16 21:39:31",
    "time_zone": "America/New_York",
    "unsubscribed_date": "",
    "list_id": 1,
    "status": "Active",
    "subscriber_status": "Active",
    "deleted_date": "0000-00-00 00:00:00",
    "default_from_name": "First List",
    "default_from_email": "myfrommail@gmail.com",
    "default_reply_email": "",
    "default_subject": "First List",
    "description": "",
    "signup_method": "Manual",
    "signup_url": "",
    "date_added": "2017-01-16 21:39:31"
  },
  {
    "subscribe_id": 15,
    "subscribed": "Yes",
    "email": "webformtest09@gmail.com",
    "first_name": "WebForm",
    "last_name": "Test01",
    "subscribed_date": "2017-01-16 21:39:30",
    "time_zone": "America/New_York",
    "unsubscribed_date": "",
    "list_id": 1,
    "status": "Active",
    "subscriber_status": "Active",
    "deleted_date": "0000-00-00 00:00:00",
    "default_from_name": "First List",
    "default_from_email": "myfrommail@gmail.com",
    "default_reply_email": "",
    "default_subject": "First List",
    "description": "",
    "signup_method": "Manual",
    "signup_url": "",
    "date_added": "2017-01-16 21:39:30"
  }
]

Following shows response object for list_id not provided:

[
  {
    "subscribe_id": 1,
    "subscribed": "Yes",
    "email": "webformtest01@gmail.com",
    "status": "Active",
    "deleted_date": "0000-00-00 00:00:00"
  },
  {
    "subscribe_id": 2,
    "subscribed": "Yes",
    "email": "newfieldstest01@gmail.com",
    "status": "Active",
    "deleted_date": "0000-00-00 00:00:00"
  },
]

Retrieves subscribers information.

HTTP Request

POST /api/v1/list-subscribers

Query Parameters

Parameter Description
api Your API key
hash Your Hash key
list_id List id (used to find subscribers of a specific list)
subscribed Subscribed status of subscriber (Yes or No)
status Status of subscriber (Active, Pending or Deleted)
start Starting offset from which searching will be performed (default is 1)
limit Maximum count of subscribers returned (default is 10)

Errors

The Betasend API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized or disabled – Invalid API key or the api has been disabled.
405 Method Not Allowed – You tried to access invalid api.
406 Not Acceptable – You requested a format that isn’t json or some input parameters don’t have proper format.
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.