Skill v1.0.0
currentAutomated scan100/100version: "1.0.0"
EmailBison API — Complete Documentation
Source: https://docs.emailbison.com + https://dedi.emailbison.com/api/reference API Version: v1.0.0 (OAS 3.0.3) Base URL: https://dedi.emailbison.com (or your custom instance URL) Scraped: 2026-04-10
Example Instance — Quick Reference
| Field | Value | ||
|---|---|---|---|
| Instance URL | https://send.example-mail.com | ||
| API Key | `2\ | 5KmZhWXg08i0OjsHgSSeC0WtEFEvIGDGODpC0KbN9b6d783f` | |
| Auth Header | `Authorization: Bearer 2\ | 5KmZhWXg08i0OjsHgSSeC0WtEFEvIGDGODpC0KbN9b6d783f` | |
| UI | https://send.example-mail.com |
Merge Tags (Email Bison Syntax)
Email Bison uses single curly braces + UPPERCASE for all variables:
| Token | What it does | |
|---|---|---|
{FIRST_NAME} | Lead's first name | |
{LAST_NAME} | Lead's last name | |
{EMAIL} | Lead's email | |
{COMPANY} | Lead's company | |
{TITLE} | Lead's job title | |
{SENDER_EMAIL_SIGNATURE} | Sender's signature block | |
{CUSTOM_VARIABLE_NAME} | Any custom variable (uppercase, underscores) |
NOT the same as SmartLead. SmartLead uses {{first_name}} (double curly, lowercase). Email Bison uses {FIRST_NAME} (single curly, uppercase). Do not mix them.
Campaign Naming Convention (Client Standard)
QFY | ProgramType | Channel | CampaignType | CampaignName
Examples:
Q2FY26 | Targeted Events | Email | Launch | Portland WTS Dinner 5/6Q2FY26 | Brand Campaign | Email | Pre-Launch | CMO Marketing Leadership
Standard Campaign Settings (example)
{"max_emails_per_day": 700,"max_new_leads_per_day": 700,"plain_text": true,"open_tracking": false,"can_unsubscribe": false}
Standard Schedule (example)
{"monday": true, "tuesday": true, "wednesday": true,"thursday": true, "friday": true, "saturday": false, "sunday": false,"start_time": "09:00", "end_time": "18:00","timezone": "America/New_York"}
CSV Bulk Upload Column Mapping
Use flat key mapping (NOT array indexed):
curl 'https://send.example-mail.com/api/leads/bulk/csv' \--request POST \--header 'Authorization: Bearer 2|5KmZhWXg08i0OjsHgSSeC0WtEFEvIGDGODpC0KbN9b6d783f' \--form 'name=Lead List Name' \--form 'csv=@/path/to/file.csv' \--form 'columnsToMap[first_name]=First Name' \--form 'columnsToMap[last_name]=Last Name' \--form 'columnsToMap[email]=Email' \--form 'columnsToMap[company]=Company' \--form 'columnsToMap[title]=Title'
Gotchas (Learned from Usage)
wait_in_daysminimum is 1 (not 0) — even for the first step- CSV column mapping uses
columnsToMap[field_name]=CSV Headerformat (NOTcolumnsToMap[0][field_name]) - Apostrophes in email body: use Python
json.dumps()to build the payload safely — shell quoting breaks JSON - Lead list upload is async — status starts as "Unprocessed", leads sync within ~5 minutes
- Attaching leads to an active campaign takes up to 5 minutes to sync
Table of Contents
- Authentication
- Pagination
- Terminology & Parameters
- Workspaces
- Account Management
- Email Accounts (Sender Emails)
- Campaigns
- Campaign Sequences
- Campaign Schedule
- Leads
- Custom Variables
- Tags
- Master Inbox / Replies
- Webhooks
- Email & Domain Blocklist
- Custom Tracking Domains
- Campaign Events / Analytics
- Warmup
- Reply Templates
- Scheduled Emails
- Clay Integration
- Bulk Uploader Tool
- Walkthroughs
Authentication
EmailBison uses Bearer tokens for all API requests.
Token Types
| Type | Scope | Notes | |
|---|---|---|---|
api-user | Single workspace only | Recommended. Simpler to manage. | |
super-admin | Impersonates the creating user | Scoped to one workspace at a time; changes if user switches workspace. Required for workspace creation, user creation, and API key generation. |
Creating Tokens
- UI:
Settings->Developer API->New API Token - API:
POST /api/workspaces/v1.1/{team_id}/api-tokens(requires super-admin key) - Body:
{ "name": "token name" }
Authorization Header
All requests must include:
Authorization: Bearer YOUR_API_KEY
Example:
curl https://dedi.emailbison.com/api/users \--header 'Authorization: Bearer 9|q8kSmhjJRqJVT2kc1M0ezX640Pxk'
Pagination
Paginated responses return 15 entries per page. Response structure:
{"data": [...],"links": {"first": "https://dedi.emailbison.com/api/leads?page=1","last": "https://dedi.emailbison.com/api/leads?page=4","prev": null,"next": "https://dedi.emailbison.com/api/leads?page=2"},"meta": {"current_page": 1,"from": 1,"last_page": 4}}
Retrieving pages: Append ?page={page_number} to any paginated endpoint.
Programmatic pagination: Loop requests, incrementing page number until meta.last_page is reached, or follow links.next until it is null.
Terminology & Parameters
Base URL
Each EmailBison instance has its own base URL (the same URL you log in at). Example: https://send.greenmarketing.com. All endpoint paths are relative to this.
Parameter Types
| Type | Format | Notes | |
|---|---|---|---|
| Path | /api/campaigns/{campaign_id} | Replace {param} including brackets with the value | |
| Query | ?folder=inbox&status=interested | Append to URL with ? and & separators | |
| Body | JSON {"key": "value"} | Content-Type: application/json (unless file upload, then multipart/form-data) |
Query parameter arrays: Use bracket syntax: ?tag_ids[]=1&tag_ids[]=2&tag_ids[]=3
Body parameters can be sent as query parameters if the parameter names match (EmailBison auto-converts).
Workspaces
Workspaces separate workflows into isolated environments. One workspace per client is recommended.
Scope: Every record (leads, tags, custom variables, campaigns) is unique per workspace and has its own ID. Exception: Sender emails can only exist in one workspace at a time.
Endpoints (v1.1)
| Method | Endpoint | Description | Auth | |
|---|---|---|---|---|
GET | /api/workspaces/v1.1 | List all workspaces | super-admin | |
POST | /api/workspaces/v1.1 | Create workspace | super-admin | |
GET | /api/workspaces/v1.1/{team_id} | Get workspace details | super-admin | |
PUT | /api/workspaces/v1.1/{team_id} | Update workspace | super-admin | |
DELETE | /api/workspaces/v1.1/{team_id} | Delete workspace | super-admin | |
POST | /api/workspaces/v1.1/switch-workspace | Switch active workspace | super-admin | |
POST | /api/workspaces/v1.1/users | Create new user | super-admin | |
POST | /api/workspaces/v1.1/{team_id}/api-tokens | Create API key for workspace | super-admin | |
POST | /api/workspaces/v1.1/invite-members | Invite member to workspace | api-user/super-admin | |
POST | /api/workspaces/v1.1/accept/{team_invitation_id} | Accept invitation | api-user/super-admin | |
DELETE | /api/workspaces/v1.1/members/{user_id} | Remove member | api-user/super-admin | |
GET | /api/workspaces/v1.1/master-inbox-settings | Get master inbox settings | api-user | |
PATCH | /api/workspaces/v1.1/master-inbox-settings | Update master inbox settings | api-user | |
GET | /api/workspaces/v1.1/stats | Get workspace stats | api-user | |
GET | /api/workspaces/v1.1/line-area-chart-stats | Get workspace chart stats | api-user |
Create Workspace
curl https://dedi.emailbison.com/api/workspaces/v1.1 \--request POST \--header 'Content-Type: application/json' \--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \--data '{ "name": "New Workspace" }'
Create User
curl https://dedi.emailbison.com/api/workspaces/v1.1/users \--request POST \--header 'Content-Type: application/json' \--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \--data '{"name": "John Doe","password": "securepassword","email": "example@example.com","role": "admin"}'
Roles: admin, editor, client
Invite & Accept Members
# Invitecurl https://dedi.emailbison.com/api/workspaces/v1.1/invite-members \--request POST \--header 'Content-Type: application/json' \--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \--data '{ "email": "user@example.com", "role": "admin" }'# Accept (use team_invitation_id from invite response)curl https://dedi.emailbison.com/api/workspaces/v1.1/accept/{team_invitation_id} \--request POST \--header 'Authorization: Bearer YOUR_SECRET_TOKEN'
Account Management
| Method | Endpoint | Description | |
|---|---|---|---|
GET | /api/users | Get authenticated user details | |
POST | /api/users/profile-picture | Update profile picture (multipart/form-data, jpg/jpeg/png, max 1MB) | |
PUT | /api/users/password | Update password | |
POST | /api/users/headless-ui-token | Generate headless UI token (valid 120 min, for embedded iframe OAuth flows) |
User Details Response
{"data": {"id": 1,"name": "John Doe","email": "john@doe.com","team": {"id": 1,"name": "John Doe's Team","personal_team": true,"main": true,"parent_id": null,"sender_email_limit": 100000,"warmup_limit": 100000,"has_access_to_warmup": false,"has_access_to_healthcheck": false,"total_email_verification_credits": 0,"remaining_email_verification_credits": 0},"profile_photo_url": "https://ui-avatars.com/api/?name=J&color=7F9CF5&background=EBF4FF"}}
Headless UI Token
Generate a token for embedded email account connection:
curl https://dedi.emailbison.com/api/users/headless-ui-token \--request POST \--header 'Authorization: Bearer YOUR_SECRET_TOKEN'
Use the token in an iframe: https://your-bison-url.com/headless-ui-login?token=YOUR_HEADLESS_UI_TOKEN
Note: Requesting URL must be whitelisted first.
Email Accounts (Sender Emails)
Sender emails are the accounts EmailBison sends from. Unlimited storage. Three types: Google, Microsoft, Custom SMTP. Sender emails can only exist in one workspace at a time.
Endpoints
| Method | Endpoint | Description | |
|---|---|---|---|
GET | /api/sender-emails | List all sender emails | |
GET | /api/sender-emails/{id} | Get sender email details | |
PATCH | /api/sender-emails/{id} | Update sender email | |
DELETE | /api/sender-emails/{id} | Delete sender email | |
GET | /api/sender-emails/{id}/campaigns | Get campaigns for sender email | |
GET | /api/sender-emails/{id}/replies | Get replies for sender email | |
GET | /api/sender-emails/{id}/oauth-access-token | Get OAuth access token | |
PATCH | /api/sender-emails/signatures/bulk | Bulk update signatures | |
PATCH | /api/sender-emails/daily-limits/bulk | Bulk update daily limits | |
POST | /api/sender-emails/imap-smtp | Add custom SMTP account (CSV upload) | |
POST | /api/sender-emails/bulk | Bulk add sender emails (CSV upload) | |
POST | /api/sender-emails/{id}/check-mx-records | Check MX records | |
POST | /api/sender-emails/bulk-check-missing-mx-records | Bulk check missing MX records |
Add Custom SMTP Accounts (CSV)
curl https://dedi.emailbison.com/api/sender-emails/imap-smtp \--request POST \--header 'Content-Type: multipart/form-data' \--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \--form 'csv=@/path/to/accounts.csv'
Bulk Add Sender Emails
curl https://dedi.emailbison.com/api/sender-emails/bulk \--request POST \--header 'Content-Type: multipart/form-data' \--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \--form 'csv=@/path/to/accounts.csv'
Campaigns
Campaigns orchestrate emails: what gets sent, to whom, and when.
Key behaviors:
- Smart scheduling: random send pattern within your sending window to avoid automation detection
- ESP Matching: unopinionated — EmailBison tags leads with their ESP, you decide matching strategy
- Lead-sender affinity: once a lead gets an email from a sender, that sender handles all remaining steps + followup campaigns
- Campaign scheduler runs on resume and at end of each sending day
Campaign Endpoints
| Method | Endpoint | Description | |
|---|---|---|---|
GET | /api/campaigns | List all campaigns | |
POST | /api/campaigns | Create campaign (body: { "name": "..." }) | |
GET | /api/campaigns/{id} | Get campaign details + settings | |
PATCH | /api/campaigns/{id}/update | Update campaign settings | |
POST | /api/campaigns/{id}/duplicate | Duplicate campaign | |
PATCH | /api/campaigns/{id}/pause | Pause campaign | |
PATCH | /api/campaigns/{id}/resume | Resume/launch campaign | |
PATCH | /api/campaigns/{id}/archive | Archive campaign | |
DELETE | /api/campaigns/{id} | Delete campaign | |
DELETE | /api/campaigns/bulk | Bulk delete campaigns | |
POST | /api/campaigns/{id}/stats | Get campaign stats | |
GET | /api/campaigns/{id}/line-area-chart-stats | Get chart stats | |
GET | /api/campaigns/{id}/replies | Get campaign replies | |
GET | /api/campaigns/{id}/leads | Get campaign leads | |
DELETE | /api/campaigns/{id}/leads | Remove all leads from campaign | |
GET | /api/campaigns/{id}/sender-emails | Get campaign sender emails | |
GET | /api/campaigns/{id}/scheduled-emails | Get scheduled emails |
Campaign Settings
Update via PATCH /api/campaigns/{id}/update:
| Field | Type | Default | Description | |
|---|---|---|---|---|
max_emails_per_day | integer/null | 1000 | Max emails sent per day | |
max_new_leads_per_day | integer/null | 1000 | Max new leads added per day | |
plain_text | boolean/null | false | Send as plain text | |
open_tracking | boolean/null | false | Enable open tracking | |
reputation_building | boolean/null | false | Spam protection | |
can_unsubscribe | boolean/null | false | Enable one-click unsubscribe | |
unsubscribe_text | string/null | - | Unsubscribe link text |
curl 'https://dedi.emailbison.com/api/campaigns/{id}/update' \--request PATCH \--header 'Content-Type: application/json' \--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \--data '{"max_emails_per_day": 500,"max_new_leads_per_day": 100,"plain_text": true,"open_tracking": true,"can_unsubscribe": true,"unsubscribe_text": "Click here to unsubscribe"}'
Adding Leads to Campaign
| Method | Endpoint | Description | |
|---|---|---|---|
POST | /api/campaigns/{id}/leads/attach-lead-list | Attach a lead list | |
POST | /api/campaigns/{id}/leads/attach-leads | Attach individual leads by ID | |
POST | /api/campaigns/{id}/leads/stop-future-emails | Stop future emails for leads | |
POST | /api/campaigns/{id}/leads/move-to-another-campaign | Move leads to another campaign |
Note: Adding leads to an active campaign takes up to 5 minutes to sync.
# Attach by lead listcurl 'https://dedi.emailbison.com/api/campaigns/6/leads/attach-lead-list' \--request POST \--header 'Content-Type: application/json' \--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \--data '{ "lead_list_id": 1 }'# Attach by lead IDscurl 'https://dedi.emailbison.com/api/campaigns/6/leads/attach-leads' \--request POST \--header 'Content-Type: application/json' \--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \--data '{ "lead_ids": [1, 2, 3] }'
Adding/Removing Sender Emails to Campaign
# AttachPOST /api/campaigns/{campaign_id}/attach-sender-emailsBody: { "sender_email_ids": [1, 2, 3] }# RemoveDELETE /api/campaigns/{campaign_id}/remove-sender-emailsBody: { "sender_email_ids": [1, 2, 3] }
Campaign Sequences
Sequences are the email steps sent in a campaign.
Endpoints
| Method | Endpoint | Description | |
|---|---|---|---|
GET | /api/campaigns/{id}/sequence-steps | Get sequence steps | |
POST | /api/campaigns/{id}/sequence-steps | Create sequence steps | |
PUT | /api/campaigns/sequence-steps/{sequence_id} | Update a sequence step | |
PATCH | /api/campaigns/sequence-steps/{id}/activate-or-deactivate | Toggle step active/inactive | |
DELETE | /api/campaigns/sequence-steps/{id} | Delete a sequence step | |
POST | /api/campaigns/sequence-steps/{id}/test-email | Send test email for step |
v1.1 Sequence Endpoints (newer)
| Method | Endpoint | Description | |
|---|---|---|---|
GET | /api/campaigns/v1.1/{id}/sequence-steps | Get sequence steps (v1.1) | |
POST | /api/campaigns/v1.1/{id}/sequence-steps | Create sequence steps (v1.1) | |
PUT | /api/campaigns/v1.1/sequence-steps/{sequence_id} | Update a sequence step (v1.1) |
Sequence Step Fields
| Field | Type | Required | Description | |
|---|---|---|---|---|
title | string | yes | Title of the sequence | |
email_subject | string | yes | Email subject. Variables: {VARIABLE_NAME} (uppercase, curly braces) | |
email_body | string | yes | Email body. Variables: {VARIABLE_NAME} (must exist as custom variables) | |
wait_in_days | integer | yes | Days before next step | |
thread_reply | boolean | yes | Whether step is a reply to previous step | |
variant | boolean/null | no | Whether step is an A/B variant | |
variant_from_step | integer/null | conditional | Required if variant is true. ID of the step this is a variant of |
Create Sequence Example
curl 'https://dedi.emailbison.com/api/campaigns/{campaign_id}/sequence-steps' \--request POST \--header 'Content-Type: application/json' \--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \--data '{"title": "Initial outreach","sequence_steps": [{"email_subject": "Hey {FIRST_NAME}","order": 1,"email_body": "You should check this out!","wait_in_days": 3,"thread_reply": false},{"email_subject": "Following up","order": 2,"email_body": "Just checking in...","wait_in_days": 3,"thread_reply": true}]}'
Campaign Schedule
Endpoints
| Method | Endpoint | Description | |
|---|---|---|---|
POST | /api/campaigns/{id}/schedule | Create schedule | |
GET | /api/campaigns/{id}/schedule | Get campaign schedule | |
PUT | /api/campaigns/{id}/schedule | Update campaign schedule | |
GET | /api/campaigns/schedule/templates | List schedule templates | |
GET | /api/campaigns/schedule/available-timezones | List available timezones | |
GET | /api/campaigns/sending-schedules | List all sending schedules | |
GET | /api/campaigns/{id}/sending-schedule | Get campaign sending schedule | |
POST | /api/campaigns/{id}/create-schedule-from-template | Create from template |
Schedule Fields
| Field | Type | Required | Description | |
|---|---|---|---|---|
monday-sunday | boolean | yes | Whether to send on that day | |
start_time | string | yes | Start time HH:MM format (e.g., "09:00") | |
end_time | string | yes | End time HH:MM format (e.g., "17:00") | |
timezone | string | yes | Timezone string (e.g., "America/New_York") | |
save_as_template | boolean | yes | Save as reusable template |
Create Schedule Example
curl 'https://dedi.emailbison.com/api/campaigns/{campaign_id}/schedule' \--request POST \--header 'Content-Type: application/json' \--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \--data '{"monday": true, "tuesday": true, "wednesday": true,"thursday": true, "friday": true, "saturday": false, "sunday": false,"start_time": "09:00", "end_time": "17:00","timezone": "America/New_York","save_as_template": false}'
Common Timezone Strings
| Timezone | String | |
|---|---|---|
| US Eastern | America/New_York | |
| US Central | America/Chicago | |
| US Mountain | America/Denver | |
| US Pacific | America/Los_Angeles | |
| UK | Europe/London | |
| Central Europe | Europe/Berlin | |
| Australia East | Australia/Sydney |
Leads
Leads (contacts) are email addresses targeted by campaigns. Unlimited storage. CSVs and campaigns limited to 50,000 leads at once.
Key behaviors:
- Same lead (email) can exist in multiple workspaces (separate IDs)
- Updating a CSV with same emails updates leads in-place (including in active campaigns)
- Every lead auto-tagged with their ESP (for ESP matching)
Endpoints
| Method | Endpoint | Description | |
|---|---|---|---|
GET | /api/leads | List all leads (paginated) | |
POST | /api/leads | Create single lead | |
GET | /api/leads/{lead_id} | Get lead details | |
PUT | /api/leads/{lead_id} | Update lead (full) | |
PATCH | /api/leads/{lead_id} | Update lead (partial) | |
DELETE | /api/leads/{lead_id} | Delete lead | |
GET | /api/leads/{lead_id}/replies | Get replies for lead | |
GET | /api/leads/{lead_id}/sent-emails | Get sent emails for lead | |
GET | /api/leads/{lead_id}/scheduled-emails | Get scheduled emails for lead | |
POST | /api/leads/multiple | Create multiple leads | |
POST | /api/leads/create-or-update/multiple | Create or update multiple leads | |
POST | /api/leads/create-or-update/{lead_id} | Create or update single lead | |
PATCH | /api/leads/{lead_id}/unsubscribe | Unsubscribe lead | |
POST | /api/leads/{lead_id}/blacklist | Blacklist lead | |
POST | /api/leads/bulk/csv | Bulk upload via CSV | |
PATCH | /api/leads/{lead_id}/update-status | Update lead status | |
PATCH | /api/leads/bulk-update-status | Bulk update lead status | |
DELETE | /api/leads/bulk | Bulk delete leads |
Create Single Lead
Required fields: first_name, last_name, email Optional fields: title, company, notes, custom_variables
curl https://dedi.emailbison.com/api/leads \--request POST \--header 'Content-Type: application/json' \--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \--data '{"first_name": "John","last_name": "Doe","email": "john@doe.com","title": "Engineer","company": "Acme Corp","notes": "Important client","custom_variables": [{ "name": "phone number", "value": "9059999999" }]}'
Bulk Upload Leads (CSV)
50,000 lead limit per CSV file. Do NOT set Content-Type header (auto-set to multipart/form-data).
| Field | Type | Required | Description | |
|---|---|---|---|---|
name | string | yes | Name of the lead list to create | |
csv | FILE | yes | The CSV file | |
columnsToMap[first_name][] | string | yes | CSV header for first_name | |
columnsToMap[last_name][] | string | yes | CSV header for last_name | |
columnsToMap[email][] | string | yes | CSV header for email | |
columnsToMap[{OTHER}][] | string | no | Additional field mappings including custom variables |
curl https://dedi.emailbison.com/api/leads/bulk/csv \--request POST \--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \--form 'name=My Lead List' \--form 'csv=@/path/to/list.csv' \--form 'columnsToMap[0][first_name]=name' \--form 'columnsToMap[0][last_name]=last name' \--form 'columnsToMap[0][email]=email' \--form 'columnsToMap[0][company]=company name'
Custom Variables
Custom variables attach arbitrary data to leads. Unique per workspace — must be created before attaching to leads.
Endpoints
| Method | Endpoint | Description | |
|---|---|---|---|
GET | /api/custom-variables | List all custom variables | |
POST | /api/custom-variables | Create custom variable (body: { "name": "..." }) |
Attaching to Leads
When creating or updating a lead, pass custom_variables as an array:
{"first_name": "John","last_name": "Doe","email": "john@doe.com","custom_variables": [{ "name": "phone_number", "value": "123-456-7890" },{ "name": "linkedin_url", "value": "https://linkedin.com/in/johndoe" }]}
Using Variables in Email Copy
Reference variables in email subjects/bodies with uppercase curly brace syntax:
Hey {FIRST_NAME}, I noticed {COMPANY} is growing...
Variables must exist as custom variables in the workspace.
Tags
Tags organize leads, campaigns, and sender emails. Unique per workspace. Emit webhooks on attach/remove.
Default Tags (auto-created per workspace)
Interested, Meeting Booked, Google, Outlook, Zoho, Custom Mail Server, Proofpoint, Mimecast, Barracuda, Automated Reply
Endpoints
| Method | Endpoint | Description | |
|---|---|---|---|
GET | /api/tags | List all tags | |
POST | /api/tags | Create tag | |
GET | /api/tags/{id} | Get tag | |
DELETE | /api/tags/{tag_id} | Delete tag | |
POST | /api/tags/attach-to-leads | Attach tags to leads | |
POST | /api/tags/attach-to-campaigns | Attach tags to campaigns | |
POST | /api/tags/attach-to-sender-emails | Attach tags to sender emails | |
POST | /api/tags/remove-from-leads | Remove tags from leads | |
POST | /api/tags/remove-from-campaigns | Remove tags from campaigns | |
POST | /api/tags/remove-from-sender-emails | Remove tags from sender emails |
Create Tag
curl https://dedi.emailbison.com/api/tags \--request POST \--header 'Content-Type: application/json' \--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \--data '{ "name": "Important", "default": false }'
Attach/Remove Tags
Body requires tag_ids array + one of lead_ids, campaign_ids, or sender_email_ids:
# Attach tags 1,2 to sender emails 3,4curl https://dedi.emailbison.com/api/tags/attach-to-sender-emails \--request POST \--header 'Content-Type: application/json' \--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \--data '{ "tag_ids": [1, 2], "sender_email_ids": [3, 4] }'# Remove tags (same body format, same endpoints, use POST for remove-from-*)
Master Inbox / Replies
The Master Inbox is a unified view into all sender email accounts in a workspace.
Filtering: By campaigns, reply statuses, sender emails, lead tags. Smart filter: Toggle Smart filter warmup emails from other providers in Settings -> Master Inbox. Add ignore phrases for remaining warmup emails.
Reply Endpoints
| Method | Endpoint | Description | |
|---|---|---|---|
GET | /api/replies | List all replies | |
GET | /api/replies/{id} | Get reply details | |
POST | /api/replies/new | Compose new email | |
POST | /api/replies/{reply_id}/reply | Reply to a message | |
POST | /api/replies/{reply_id}/forward | Forward a message | |
PATCH | /api/replies/{reply_id}/mark-as-interested | Mark as interested | |
PATCH | /api/replies/{reply_id}/mark-as-not-interested | Mark as not interested | |
PATCH | /api/replies/{reply_id}/mark-as-read-or-unread | Toggle read/unread | |
PATCH | /api/replies/{reply_id}/mark-as-automated-or-not-automated | Toggle automated | |
PATCH | /api/replies/{reply_id}/unsubscribe | Unsubscribe lead | |
DELETE | /api/replies/{reply_id} | Delete reply | |
GET | /api/replies/{reply_id}/conversation-thread | Get conversation thread | |
POST | /api/replies/{reply_id}/attach-scheduled-email-to-reply | Attach scheduled email | |
POST | /api/replies/{reply_id}/followup-campaign/push | Push to followup campaign |
Fetching Replies for a Lead
GET /api/leads/{lead_id}/replies
Query parameters:
| Param | Type | Description | |
|---|---|---|---|
search | string | Search term | |
status | string | One of: interested, automated_reply, not_automated_reply | |
folder | string | One of: inbox, sent, spam, bounced, all | |
read | boolean | Filter by read status | |
campaign_id | integer | Filter by campaign | |
sender_email_id | integer | Filter by sender email | |
tag_ids | array | Filter by tag IDs |
Getting Sent Emails for a Lead
GET /api/leads/{lead_id_or_email}/sent-emails
Responding to Messages
POST /api/replies/{reply_id}/reply
| Field | Type | Required | Description | |
|---|---|---|---|---|
reply_id | integer (path) | yes | Parent reply ID | |
message | string | yes | Reply contents | |
sender_email_id | integer | yes | Sender email ID | |
to_emails | array | yes | [{"name": "John", "email_address": "john@example.com"}] | |
inject_previous_email_body | boolean | no | Include previous email body (default: false) | |
content_type | string | no | html or text | |
cc_emails | array | no | CC recipients (same format as to_emails) | |
bcc_emails | array | no | BCC recipients (same format as to_emails) |
Attaching Leads to Untracked Replies
- Get scheduled emails:
GET /api/scheduled-emails/{lead_id_or_email} - Attach to reply:
POST /api/replies/{reply_id}/attach-email-to-replywith body{ "scheduled_email_id": 123 }
Webhooks
Webhooks send HTTP POST requests when events occur in your EmailBison instance.
Endpoints
| Method | Endpoint | Description | |
|---|---|---|---|
GET | /api/webhook-url | List all webhooks | |
POST | /api/webhook-url | Create webhook | |
GET | /api/webhook-url/{id} | Get webhook details | |
PUT | /api/webhook-url/{id} | Update webhook | |
DELETE | /api/webhook-url/{id} | Delete webhook | |
GET | /api/webhook-events/sample-payload | Get sample payload | |
GET | /api/webhook-events/event-types | List all event types | |
POST | /api/webhook-events/test-event | Send test event |
Available Webhook Events
| Event | Trigger | |
|---|---|---|
| Email Sent | Campaign email is sent | |
| Manual Email Sent | Manual email sent (reply or compose, from inbox or API) | |
| Contact First Emailed | Contact receives first campaign email on this workspace | |
| Contact Replied | Lead emailed from a campaign replies. NOT triggered if auto-reply + "Include auto replies in stats" is off | |
| Contact Interested | Reply marked as interested (manually, via API, or auto AI categorization) | |
| Contact Unsubscribed | Lead unsubscribed from campaigns | |
| Untracked Reply Received | Email received not associated with a campaign scheduled email | |
| Email Opened | Email opened (requires track opens enabled on campaign) | |
| Email Bounced | Campaign email bounces | |
| Email Account Added | Sender email connected for first time | |
| Email Account Removed | Sender email deleted | |
| Email Account Disconnected | Sender email disconnected (incl. Microsoft token expiry) | |
| Email Account Reconnected | Sender email reconnected after disconnect | |
| Tag Attached | Custom tag attached (one webhook per tag per taggable) | |
| Tag Removed | Custom tag removed (one webhook per tag per taggable) | |
| Warmup Disabled Causing Bounces | Warmup disabled for causing too many bounces | |
| Warmup Disabled Receiving Bounces | Warmup disabled for receiving too many bounces |
Testing Webhooks
Via UI: Settings -> Webhooks -> Edit -> Send test webhook Via API: POST /api/webhook-events/test-event
Email & Domain Blocklist
Email Blocklist
| Method | Endpoint | Description | |
|---|---|---|---|
GET | /api/blacklisted-emails | List blocked emails | |
POST | /api/blacklisted-emails | Add email to blocklist | |
GET | /api/blacklisted-emails/{id} | Get blocked email | |
DELETE | /api/blacklisted-emails/{id} | Remove from blocklist | |
POST | /api/blacklisted-emails/bulk | Bulk add to blocklist |
Domain Blocklist
| Method | Endpoint | Description | |
|---|---|---|---|
GET | /api/blacklisted-domains | List blocked domains | |
POST | /api/blacklisted-domains | Add domain to blocklist | |
GET | /api/blacklisted-domains/{id} | Get blocked domain | |
DELETE | /api/blacklisted-domains/{id} | Remove from blocklist | |
POST | /api/blacklisted-domains/bulk | Bulk add to blocklist |
Custom Tracking Domains
| Method | Endpoint | Description | |
|---|---|---|---|
GET | /api/custom-tracking-domain | List tracking domains | |
POST | /api/custom-tracking-domain | Create tracking domain | |
GET | /api/custom-tracking-domain/{id} | Get tracking domain | |
DELETE | /api/custom-tracking-domain/{id} | Delete tracking domain |
Campaign Events / Analytics
Drill down into campaign event stats by dates, campaign IDs, and/or sender email IDs.
| Method | Endpoint | Description | |
|---|---|---|---|
GET | /api/campaign-events/stats | Get campaign event stats |
Warmup
Manage warmup settings for email accounts.
| Method | Endpoint | Description | |
|---|---|---|---|
GET | /api/warmup/sender-emails | List warmup sender emails | |
PATCH | /api/warmup/sender-emails/enable | Enable warmup | |
PATCH | /api/warmup/sender-emails/disable | Disable warmup | |
PATCH | /api/warmup/sender-emails/update-daily-warmup-limits | Update daily warmup limits | |
GET | /api/warmup/sender-emails/{id} | Get warmup details for sender email |
Reply Templates
Manage templated responses for replying to leads.
| Method | Endpoint | Description | |
|---|---|---|---|
GET | /api/reply-templates | List all reply templates | |
POST | /api/reply-templates | Create reply template | |
GET | /api/reply-templates/{id} | Get reply template | |
PUT | /api/reply-templates/{id} | Update reply template | |
DELETE | /api/reply-templates/{id} | Delete reply template |
Scheduled Emails
| Method | Endpoint | Description | |
|---|---|---|---|
GET | /api/scheduled-emails | List all scheduled emails | |
GET | /api/scheduled-emails/{id} | Get scheduled email details |
Ignore Phrases
Filter out warmup/noise emails from master inbox.
| Method | Endpoint | Description | |
|---|---|---|---|
GET | /api/ignore-phrases | List all ignore phrases | |
POST | /api/ignore-phrases | Create ignore phrase | |
GET | /api/ignore-phrases/{id} | Get ignore phrase | |
DELETE | /api/ignore-phrases/{id} | Delete ignore phrase |
Clay Integration
EmailBison has an official Clay integration with native enrichments.
Setup
- Create API key: Generate an
api-userkey in EmailBison (Settings->Developer API) - Connect in Clay:
Settings->Connections->+ Add connection-> searchEmailBison
- Connection name: workspace name
- Workspace domain (Instance URL): your EmailBison URL
- API Key: your api-user key
- Each workspace needs its own connection
Native Enrichments
| Enrichment | Description | |
|---|---|---|
| Find Lead | Search for and retrieve lead information | |
| Create or Update Lead | Add new leads or update existing ones | |
| Import Lead(s) to Campaign | Add leads to specific campaigns | |
| Add Email to Blocklist | Block specific email addresses | |
| Add Domain to Blocklist | Block specific domains | |
| Remove Email from Blocklist | Unblock email addresses | |
| Remove Domain from Blocklist | Unblock domains |
HTTP API Enrichment (for non-native requests)
GET requests: Use Clay's HTTP API enrichment with GET method, paste endpoint URL, add query parameters in Body section.
POST requests (e.g., creating leads):
- Add
HTTP APIenrichment, select POST method - Authenticate via saved account or Authorization header
- Map Clay columns to JSON body fields using
/to reference columns - For custom fields, use
custom_variablesarray - To attach leads to campaigns, chain a second HTTP API enrichment using the lead ID returned from step 1
Bulk Uploader Tool
Native desktop tool for bulk uploading Microsoft accounts. Available for Windows, macOS, Linux.
Download:
- Windows:
https://dedi.emailbison.com/microsoft-uploader/emailbison_uploader_windows.zip - macOS:
https://dedi.emailbison.com/microsoft-uploader/emailbison_uploader_mac.zip - Linux:
https://dedi.emailbison.com/microsoft-uploader/emailbison_uploader_linux.zip
Key Flags
| Flag | Type | Default | Description | |
|---|---|---|---|---|
--non-interactive | boolean | false | Disable all prompts (requires --csv-file) | |
--browsers | integer | 6 (1-16) | Concurrent browsers | |
--no-headless | boolean | false | Show browser windows (use with --browsers 1) | |
--timeout | integer | 75 (30-180) | Seconds before treating email as failed | |
--tag | string | "" | Tag batch of emails | |
--skip-connected-accounts | boolean | false | Skip already-connected accounts | |
--config-file | string | "config.txt" | Custom config file path | |
--csv-file | string | "" | Path to CSV file | |
--throttle | boolean | false | Throttle sign-in speed | |
--driver | string | "rod" | Browser driver: "rod" or "chromedp" |
CSV Format
Headers: name, email, password Optional column: use_as_admin (for admin consent prompt)
Admin Consent Fix
For "Need Admin Approval" errors: include one account per tenant with "Cloud Applications Admin" role, mark use_as_admin=true in CSV.
Walkthroughs
Creating Template Workspaces
Automate workspace creation with standard setup (users, tags, API tokens, webhooks):
POST /api/workspaces/v1.1(create workspace, needs super-admin)POST /api/workspaces/v1.1/{team_id}/api-tokens(create api-user key)- Switch to api-user key for remaining requests
POST /api/workspaces/v1.1/invite-members(for each user)POST /api/workspaces/v1.1/accept/{team_invitation_id}(accept each)POST /api/tags(for each tag)POST /api/webhook-url(create webhook with desired events)
Slack Notification on Campaign Reply
- Create webhook in EmailBison:
Settings->Webhooks->New Webhook URL - Subscribe to
Contact Repliedevent - Point webhook URL to your automation tool (n8n, Zapier, etc.)
- Parse webhook payload and send Slack message
Complete Campaign Launch Workflow (API)
- Create campaign:
POST /api/campaignswith{ "name": "..." } - Update settings:
PATCH /api/campaigns/{id}/update(limits, tracking, etc.) - Create schedule:
POST /api/campaigns/{id}/schedule(days, times, timezone) - Create sequence:
POST /api/campaigns/{id}/sequence-steps(email steps) - Add sender emails:
POST /api/campaigns/{id}/attach-sender-emails - Add leads:
POST /api/campaigns/{id}/leads/attach-leadsorattach-lead-list - Verify setup:
GET /api/campaigns/{id}(settings)GET /api/campaigns/{id}/schedule(schedule)GET /api/campaigns/{id}/sequence-steps(sequences)
- Launch:
PATCH /api/campaigns/{id}/resume - Pause:
PATCH /api/campaigns/{id}/pause
Full API Endpoint Index
Account Management (4)
GET /api/usersPOST /api/users/profile-picturePUT /api/users/passwordPOST /api/users/headless-ui-token
Campaigns (37)
GET /api/campaignsPOST /api/campaignsPOST /api/campaigns/{id}/duplicatePATCH /api/campaigns/{id}/pausePATCH /api/campaigns/{id}/resumePATCH /api/campaigns/{id}/archivePATCH /api/campaigns/{id}/updatePOST /api/campaigns/{id}/scheduleGET /api/campaigns/{id}/schedulePUT /api/campaigns/{id}/scheduleGET /api/campaigns/schedule/templatesGET /api/campaigns/schedule/available-timezonesGET /api/campaigns/sending-schedulesGET /api/campaigns/{id}/sending-schedulePOST /api/campaigns/{id}/create-schedule-from-templateGET /api/campaigns/{id}/sequence-stepsPOST /api/campaigns/{id}/sequence-stepsPUT /api/campaigns/sequence-steps/{sequence_id}PATCH /api/campaigns/sequence-steps/{id}/activate-or-deactivateDELETE /api/campaigns/sequence-steps/{id}POST /api/campaigns/sequence-steps/{id}/test-emailGET /api/campaigns/{id}/repliesGET /api/campaigns/{id}/leadsDELETE /api/campaigns/{id}/leadsPOST /api/campaigns/{id}/leads/attach-lead-listPOST /api/campaigns/{id}/leads/attach-leadsPOST /api/campaigns/{id}/leads/stop-future-emailsGET /api/campaigns/{id}/scheduled-emailsGET /api/campaigns/{id}/sender-emailsPOST /api/campaigns/{id}/statsPOST /api/campaigns/{id}/attach-sender-emailsDELETE /api/campaigns/{id}/remove-sender-emailsPOST /api/campaigns/{id}/leads/move-to-another-campaignGET /api/campaigns/{id}/line-area-chart-statsGET /api/campaigns/{id}DELETE /api/campaigns/bulkDELETE /api/campaigns/{id}
Campaigns v1.1 (3)
GET /api/campaigns/v1.1/{id}/sequence-stepsPOST /api/campaigns/v1.1/{id}/sequence-stepsPUT /api/campaigns/v1.1/sequence-steps/{sequence_id}
Replies (14)
GET /api/repliesGET /api/replies/{id}POST /api/replies/newPOST /api/replies/{reply_id}/replyPOST /api/replies/{reply_id}/forwardPATCH /api/replies/{reply_id}/mark-as-interestedPATCH /api/replies/{reply_id}/mark-as-not-interestedPATCH /api/replies/{reply_id}/mark-as-read-or-unreadPATCH /api/replies/{reply_id}/mark-as-automated-or-not-automatedPATCH /api/replies/{reply_id}/unsubscribeDELETE /api/replies/{reply_id}GET /api/replies/{reply_id}/conversation-threadPOST /api/replies/{reply_id}/attach-scheduled-email-to-replyPOST /api/replies/{reply_id}/followup-campaign/push
Email Accounts (13)
GET /api/sender-emailsGET /api/sender-emails/{id}/campaignsGET /api/sender-emails/{id}PATCH /api/sender-emails/{id}DELETE /api/sender-emails/{id}GET /api/sender-emails/{id}/repliesGET /api/sender-emails/{id}/oauth-access-tokenPATCH /api/sender-emails/signatures/bulkPATCH /api/sender-emails/daily-limits/bulkPOST /api/sender-emails/imap-smtpPOST /api/sender-emails/bulkPOST /api/sender-emails/{id}/check-mx-recordsPOST /api/sender-emails/bulk-check-missing-mx-records
Email Blacklist (5)
GET /api/blacklisted-emailsPOST /api/blacklisted-emailsGET /api/blacklisted-emails/{id}DELETE /api/blacklisted-emails/{id}POST /api/blacklisted-emails/bulk
Domain Blacklist (5)
GET /api/blacklisted-domainsPOST /api/blacklisted-domainsGET /api/blacklisted-domains/{id}DELETE /api/blacklisted-domains/{id}POST /api/blacklisted-domains/bulk
Tags (10)
GET /api/tagsPOST /api/tagsGET /api/tags/{id}DELETE /api/tags/{tag_id}POST /api/tags/attach-to-campaignsPOST /api/tags/remove-from-campaignsPOST /api/tags/attach-to-leadsPOST /api/tags/remove-from-leadsPOST /api/tags/attach-to-sender-emailsPOST /api/tags/remove-from-sender-emails
Custom Tracking Domains (4)
GET /api/custom-tracking-domainPOST /api/custom-tracking-domainGET /api/custom-tracking-domain/{id}DELETE /api/custom-tracking-domain/{id}
Webhooks (5)
GET /api/webhook-urlPOST /api/webhook-urlGET /api/webhook-url/{id}PUT /api/webhook-url/{id}DELETE /api/webhook-url/{id}
Webhook Events (3)
GET /api/webhook-events/sample-payloadGET /api/webhook-events/event-typesPOST /api/webhook-events/test-event
Campaign Events (1)
GET /api/campaign-events/stats
Custom Lead Variables (2)
GET /api/custom-variablesPOST /api/custom-variables
Ignore Phrases (4)
GET /api/ignore-phrasesPOST /api/ignore-phrasesGET /api/ignore-phrases/{id}DELETE /api/ignore-phrases/{id}
Leads (17)
GET /api/leadsPOST /api/leadsGET /api/leads/{lead_id}PUT /api/leads/{lead_id}PATCH /api/leads/{lead_id}DELETE /api/leads/{lead_id}GET /api/leads/{lead_id}/repliesPOST /api/leads/multiplePOST /api/leads/create-or-update/multiplePOST /api/leads/create-or-update/{lead_id}PATCH /api/leads/{lead_id}/unsubscribePOST /api/leads/{lead_id}/blacklistPOST /api/leads/bulk/csvGET /api/leads/{lead_id}/scheduled-emailsGET /api/leads/{lead_id}/sent-emailsPATCH /api/leads/{lead_id}/update-statusPATCH /api/leads/bulk-update-statusDELETE /api/leads/bulk
Reply Templates (5)
GET /api/reply-templatesPOST /api/reply-templatesGET /api/reply-templates/{id}PUT /api/reply-templates/{id}DELETE /api/reply-templates/{id}
Scheduled Emails (2)
GET /api/scheduled-emailsGET /api/scheduled-emails/{id}
Warmup (5)
GET /api/warmup/sender-emailsPATCH /api/warmup/sender-emails/enablePATCH /api/warmup/sender-emails/disablePATCH /api/warmup/sender-emails/update-daily-warmup-limitsGET /api/warmup/sender-emails/{id}
Workspaces v1.1 (15)
GET /api/workspaces/v1.1POST /api/workspaces/v1.1POST /api/workspaces/v1.1/usersPOST /api/workspaces/v1.1/{team_id}/api-tokensPOST /api/workspaces/v1.1/switch-workspaceDELETE /api/workspaces/v1.1/{team_id}PUT /api/workspaces/v1.1/{team_id}GET /api/workspaces/v1.1/{team_id}POST /api/workspaces/v1.1/invite-membersPOST /api/workspaces/v1.1/accept/{team_invitation_id}DELETE /api/workspaces/v1.1/members/{user_id}GET /api/workspaces/v1.1/master-inbox-settingsPATCH /api/workspaces/v1.1/master-inbox-settingsGET /api/workspaces/v1.1/statsGET /api/workspaces/v1.1/line-area-chart-stats
Total: ~150+ endpoints across 17 API groups
_Part of Frontal — free, open GTM skills for your AI agent. Browse the library →_