SMASHSEND API Developer Guide

This comprehensive guide covers everything you need to know to build powerful applications with the SMASHSEND API. From authentication to webhooks, learn how to leverage our platform capabilities to enhance your marketing tools.

Getting Started

To get started with the SMASHSEND API, you'll need to create an API key from your dashboard. Once you have your API key, you can use it to authenticate your requests.

All API requests should be made to the base URL: https://api.smashsend.com/v1

// Example API request using fetch
const response = await fetch('https://api.smashsend.com/v1/contacts', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

// Expected response:
{
  "contacts": {
    "items": [
      {
        "id": "ctc_B7OSYsnTUVwBPOGrgYTjvSGS",
        "createdAt": "2025-06-04T05:26:05.593Z",
        "updatedAt": "2025-06-04T05:26:05.593Z",
        "properties": {
          "email": "jane.doe@example.com",
          "firstName": "Jane",
          "lastName": "Doe"
        },
        "workspaceId": "wrk_ENGTK86JEXXckyDVJthKkPer"
      }
    ],
    "cursor": null,
    "hasMore": false
  }
}

Authentication

All requests to the SMASHSEND API require authentication. We use bearer tokens for authentication. Include your API key in the Authorization header of all requests.

// Example: Authenticating with the SMASHSEND API
const headers = {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
};

// Test authentication
const response = await fetch('https://api.smashsend.com/v1/api-keys/check', { headers });
const result = await response.json();

// Expected response:
{
  "status": "SUCCEED",
  "displayName": "My API Key",
  "role": "EDITOR"
}

Rate Limits

The SMASHSEND API has rate limits to ensure fair usage. Free accounts are limited to 60 requests per minute. Enterprise accounts have higher limits based on their plan.

If you exceed the rate limit, you'll receive a 429 Too Many Requests response. The response will include a Retry-After header indicating how many seconds to wait before making another request.

Error Handling

The SMASHSEND API uses conventional HTTP status codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided, and codes in the 5xx range indicate an error with our servers.

// Example error response
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "The request was unacceptable, often due to missing a required parameter."
}

Webhooks

Webhooks allow you to be notified about events that happen in your SMASHSEND account. Instead of having to poll the API, webhooks will send HTTP POST requests to your specified URL when certain events occur.

Common webhook events include:

CONTACT_CREATED - When a new contact is created
CONTACT_UPDATED - When a contact is updated
WORKSPACE_TEAM_MEMBER_JOINED - When a team member joins the workspace

Pagination

For endpoints that return a list of items, the SMASHSEND API uses cursor-based pagination. The response will include a has_more boolean indicating if there are more items available, and a next_cursor string that can be used to retrieve the next page.

// Example: Paginating through contacts
let cursor = null;
let allContacts = [];

do {
  const url = cursor 
    ? `https://api.smashsend.com/v1/contacts?cursor=${cursor}`
    : 'https://api.smashsend.com/v1/contacts';
    
  const response = await fetch(url, { 
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  });
  const data = await response.json();
  
  allContacts = [...allContacts, ...data.contacts.items];
  cursor = data.contacts.cursor;
  
} while (data.contacts.hasMore);

console.log(`Total contacts: ${allContacts.length}`);

Best Practices

Follow these best practices to ensure optimal integration with the SMASHSEND API:

Use webhooks instead of polling whenever possible
Cache responses when appropriate to minimize API calls
Implement proper error handling for all API requests
Use a library that automatically retries failed requests with exponential backoff