# Adding and Removing Sender Emails
Source: https://docs.emailbison.com/campaigns/adding-and-removing-sender-emails
## Adding Sender Emails
Send a `POST` request to the [following endpoint](https://dedi.emailbison.com/api/reference#tag/campaigns/post/api/campaigns/\{campaign_id}/attach-sender-emails).
```bash theme={null}
/api/campaigns/{campaign_id}/attach-sender-emails
```
The request takes 1 required body parameter:
An array containing the IDs of the sender emails to add
An example of this request:
```bash curl theme={null}
curl 'https://dedi.emailbison.com/api/campaigns/6/attach-sender-emails' \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"sender_email_ids": [1,2,3]
}'
```
```JavaScript JavaScript theme={null}
fetch('https://dedi.emailbison.com/api/campaigns/6/attach-sender-emails', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: 'Bearer YOUR_SECRET_TOKEN'
},
body: JSON.stringify({
sender_email_ids: [1, 2, 3]
})
})
```
```Python Python theme={null}
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_SECRET_TOKEN',
}
json_data = {
'sender_email_ids': [1,2,3,],
}
response = requests.post('https://dedi.emailbison.com/api/campaigns/6/attach-sender-emails', headers=headers, json=json_data)
```
## Removing Sender Emails
Send a `DELETE` request to the [following endpoint](https://dedi.emailbison.com/api/reference#tag/campaigns/delete/api/campaigns/\{campaign_id}/remove-sender-emails).
```bash theme={null}
/api/campaigns/{campaign_id}/remove-sender-emails
```
The request takes 1 required body parameter:
An array containing the IDs of the sender emails to add
An example of this request:
```bash curl theme={null}
curl 'https://dedi.emailbison.com/api/campaigns/6/remove-sender-emails' \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"sender_email_ids": [1,2,3]
}'
```
```JavaScript JavaScript theme={null}
fetch('https://dedi.emailbison.com/api/campaigns/6/remove-sender-emails', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: 'Bearer YOUR_SECRET_TOKEN'
},
body: JSON.stringify({
sender_email_ids: [1, 2, 3]
})
})
```
```Python Python theme={null}
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_SECRET_TOKEN',
}
json_data = {
'sender_email_ids': [1,2,3,],
}
response = requests.post('https://dedi.emailbison.com/api/campaigns/6/remove-sender-emails', headers=headers, json=json_data)
```
# Adding Leads to a Campaign
Source: https://docs.emailbison.com/campaigns/adding-leads-to-a-campaign
## Adding Leads
Adding leads to an active campaign will take up to 5 minutes for the leads to get synced.
This ensures that there is no interruption to the campaigns sending.
### Adding leads from existing list
Send a `POST` request to the [following endpoint](https://dedi.emailbison.com/api/reference#tag/campaigns/post/api/campaigns/\{campaign_id}/leads/attach-lead-list).
```bash theme={null}
/api/campaigns/{campaign_id}/leads/attach-lead-list
```
The request takes 1 required body parameter:
The ID of the lead list to add
An example of this request:
```bash curl theme={null}
curl '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
}'
```
```JavaScript JavaScript theme={null}
fetch('https://dedi.emailbison.com/api/campaigns/6/leads/attach-lead-list', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: 'Bearer YOUR_SECRET_TOKEN'
},
body: JSON.stringify({
lead_list_id: 1
})
})
```
```Python Python theme={null}
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_SECRET_TOKEN',
}
json_data = {
'lead_list_id': 1,
}
response = requests.post(
'https://dedi.emailbison.com/api/campaigns/6/leads/attach-lead-list',
headers=headers,
json=json_data,
)
```
### Adding leads by their IDs
You can also add individual leads to a campiagn using the lead IDs.
Send a `POST` request to the [following endpoint](https://dedi.emailbison.com/api/reference#tag/campaigns/post/api/campaigns/\{campaign_id}/leads/attach-leads).
```bash theme={null}
/api/campaigns/{campaign_id}/leads/attach-leads
```
The request takes 1 required body parameter:
An array containing the IDs of the leads to add
An example of this request:
```bash curl theme={null}
curl '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]
}'
```
```JavaScript JavaScript theme={null}
fetch('https://dedi.emailbison.com/api/campaigns/6/leads/attach-leads', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: 'Bearer YOUR_SECRET_TOKEN'
},
body: JSON.stringify({
lead_ids: [1, 2, 3]
})
})
```
```Python Python theme={null}
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_SECRET_TOKEN',
}
json_data = {
'lead_ids': [1,2,3,],
}
response = requests.post('https://dedi.emailbison.com/api/campaigns/6/leads/attach-leads', headers=headers, json=json_data)
```
Navigate to `Campaigns`.
Click on the campaign you want to add leads to.
Click the `Actions` dropdown and click `Add more contacts`.
# Creating Campaigns
Source: https://docs.emailbison.com/campaigns/creating-campaigns
This page will walk you through creating a campaign from the API.
### Creating a Campaign
Send a `POST` request to `/api/campaigns`.
You must pass 1 body parameter, `name`, which corresponds to the name of the campaign you wish to create.
If successful, you will receive a a `200 OK` with the campaign ID as part of the response.
### Campaign Settings
You can get the ID for a campaign using the UI by navigating to the campaign, clicking on the `Actions` dropdown, and then clicking `Copy ID for API`.
Alternatively, campaign IDs can be acquired with a `GET` request to `/api/campaigns`.
Each campaign has individual settings that can be changed.
You can view the settings with a `GET` request to `/api/campaigns/{id}` where `{id}` is the campaign ID.
If you need to change the settings, send a `PATCH` request to `/api/campaigns/{id}/update` where `{id}` is the campaign ID.
The maxiumum number of emails that can be sent per day
The maximum number of new leads that can be added per day.
Whether the email content should be plain text. If nothing sent, false is assumed
Whether open tracking should be enabled for the campaign. If nothing sent, false is assumed.
Spam protection. If nothing sent, false is assumed.
Whether recipients can unsubscribe from the campaign using a one-click link. If nothing sent, false is assumed.
The text that will be shown in the unsubscribe link.
```bash curl theme={null}
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,
"reputation_building": true,
"can_unsubscribe": true,
"unsubscribe_text": "Click here to unsubscribe"
}'
```
```JavaScript JavaScript theme={null}
fetch('https://dedi.emailbison.com/api/campaigns/{id}/update', {
method: 'PATCH',
headers: {
'Content-Type': 'application/json',
Authorization: 'Bearer YOUR_SECRET_TOKEN'
},
body: JSON.stringify({
max_emails_per_day: 500,
max_new_leads_per_day: 100,
plain_text: true,
open_tracking: true,
reputation_building: true,
can_unsubscribe: true,
unsubscribe_text: 'Click here to unsubscribe'
})
})
```
```Python Python theme={null}
url = "https://dedi.emailbison.com/api/campaigns/{id}/update"
payload = {
"max_emails_per_day": 500,
"max_new_leads_per_day": 100,
"plain_text": True,
"open_tracking": True,
"reputation_building": True,
"can_unsubscribe": True,
"unsubscribe_text": "Click here to unsubscribe"
}
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_SECRET_TOKEN"
}
response = requests.patch(url, json=payload, headers=headers)
```
### Campaign Schedule
If you have created a schedule for a campaign in the past, you can re-use it provided you've saved it as a template.
**If you have a schedule template you wish to use**:
Get the schedule ID by sending a `GET` request to `/api/campaigns/schedule/templates`.
Once you've acquired the ID, send a `POST` to `/api/campaigns/{campaign_id}/create-schedule-from-template`.
The request requires 1 body field, `schedule_id`, which is the ID of the schedule you want to use.
**If you don't have a schedule template you wish to use**:
If you don't have any templates, or wish to create a new one, send a `POST` request to `/api/campaigns/{campaign_id}/schedule`.
Whether the schedule includes Monday.
Whether the schedule includes Tuesday.
Whether the schedule includes Wednesday.
Whether the schedule includes Thursday.
Whether the schedule includes Friday.
Whether the schedule includes Saturday.
Whether the schedule includes Sunday.
The start time in HH:MM format.
Example: `09:00`
The end time in HH:MM format.
Example: `17:00`
The timezone of the schedule.
You need to use the formatted string after the `=>` symbol.
e.g. "America/Los\_Angeles"
(GMT-12:00) International Date Line West => **Pacific/Kwajalein**
(GMT-11:00) Midway Island => **Pacific/Midway**
(GMT-11:00) Samoa => **Pacific/Apia**
(GMT-10:00) Hawaii => **Pacific/Honolulu**
(GMT-09:00) Alaska => **America/Anchorage**
(GMT-08:00) Pacific Time (US & Canada) => **America/Los\_Angeles**
(GMT-08:00) Tijuana => **America/Tijuana**
(GMT-07:00) Arizona => **America/Phoenix**
(GMT-07:00) Mountain Time (US & Canada) => **America/Denver**
(GMT-07:00) Chihuahua => **America/Chihuahua**
(GMT-07:00) La Paz => **America/Chihuahua**
(GMT-07:00) Mazatlan => **America/Mazatlan**
(GMT-06:00) Central Time (US & Canada) => **America/Chicago**
(GMT-06:00) Central America => **America/Managua**
(GMT-06:00) Guadalajara => **America/Mexico\_City**
(GMT-06:00) Mexico City => **America/Mexico\_City**
(GMT-06:00) Monterrey => **America/Monterrey**
(GMT-06:00) Saskatchewan => **America/Regina**
(GMT-05:00) Eastern Time (US & Canada) => **America/New\_York**
(GMT-05:00) Indiana (East) => **America/Indiana/Indianapolis**
(GMT-05:00) Bogota => **America/Bogota**
(GMT-05:00) Lima => **America/Lima**
(GMT-05:00) Quito => **America/Bogota**
(GMT-04:00) Atlantic Time (Canada) => **America/Halifax**
(GMT-04:00) Caracas => **America/Caracas**
(GMT-04:00) La Paz => **America/La\_Paz**
(GMT-04:00) Santiago => **America/Santiago**
(GMT-03:30) Newfoundland => **America/St\_Johns**
(GMT-03:00) Brasilia => **America/Sao\_Paulo**
(GMT-03:00) Buenos Aires => **America/Argentina/Buenos\_Aires**
(GMT-03:00) Georgetown => **America/Argentina/Buenos\_Aires**
(GMT-03:00) Greenland => **America/Godthab**
(GMT-02:00) Mid-Atlantic => **America/Noronha**
(GMT-01:00) Azores => **Atlantic/Azores**
(GMT-01:00) Cape Verde Is. => **Atlantic/Cape\_Verde**
(GMT) Casablanca => **Africa/Casablanca**
(GMT) Dublin => **Europe/London**
(GMT) Edinburgh => **Europe/London**
(GMT) Lisbon => **Europe/Lisbon**
(GMT) London => **Europe/London**
(GMT) Monrovia => **Africa/Monrovia**
(GMT+01:00) Amsterdam => **Europe/Amsterdam**
(GMT+01:00) Belgrade => **Europe/Belgrade**
(GMT+01:00) Berlin => **Europe/Berlin**
(GMT+01:00) Bern => **Europe/Berlin**
(GMT+01:00) Bratislava => **Europe/Bratislava**
(GMT+01:00) Brussels => **Europe/Brussels**
(GMT+01:00) Budapest => **Europe/Budapest**
(GMT+01:00) Copenhagen => **Europe/Copenhagen**
(GMT+01:00) Ljubljana => **Europe/Ljubljana**
(GMT+01:00) Madrid => **Europe/Madrid**
(GMT+01:00) Paris => **Europe/Paris**
(GMT+01:00) Prague => **Europe/Prague**
(GMT+01:00) Rome => **Europe/Rome**
(GMT+01:00) Sarajevo => **Europe/Sarajevo**
(GMT+01:00) Skopje => **Europe/Skopje**
(GMT+01:00) Stockholm => **Europe/Stockholm**
(GMT+01:00) Vienna => **Europe/Vienna**
(GMT+01:00) Warsaw => **Europe/Warsaw**
(GMT+01:00) West Central Africa => **Africa/Lagos**
(GMT+01:00) Zagreb => **Europe/Zagreb**
(GMT+02:00) Athens => **Europe/Athens**
(GMT+02:00) Bucharest => **Europe/Bucharest**
(GMT+02:00) Cairo => **Africa/Cairo**
(GMT+02:00) Harare => **Africa/Harare**
(GMT+02:00) Helsinki => **Europe/Helsinki**
(GMT+02:00) Istanbul => **Europe/Istanbul**
(GMT+02:00) Jerusalem => **Asia/Jerusalem**
(GMT+02:00) Kyev => **Europe/Kiev**
(GMT+02:00) Minsk => **Europe/Minsk**
(GMT+02:00) Pretoria => **Africa/Johannesburg**
(GMT+02:00) Riga => **Europe/Riga**
(GMT+02:00) Sofia => **Europe/Sofia**
(GMT+02:00) Tallinn => **Europe/Tallinn**
(GMT+02:00) Vilnius => **Europe/Vilnius**
(GMT+03:00) Baghdad => **Asia/Baghdad**
(GMT+03:00) Kuwait => **Asia/Kuwait**
(GMT+03:00) Moscow => **Europe/Moscow**
(GMT+03:00) Nairobi => **Africa/Nairobi**
(GMT+03:00) Riyadh => **Asia/Riyadh**
(GMT+03:00) St. Petersburg => **Europe/Moscow**
(GMT+03:00) Volgograd => **Europe/Volgograd**
(GMT+03:30) Tehran => **Asia/Tehran**
(GMT+04:00) Abu Dhabi => **Asia/Muscat**
(GMT+04:00) Baku => **Asia/Baku**
(GMT+04:00) Muscat => **Asia/Muscat**
(GMT+04:00) Tbilisi => **Asia/Tbilisi**
(GMT+04:00) Yerevan => **Asia/Yerevan**
(GMT+04:30) Kabul => **Asia/Kabul**
(GMT+05:00) Ekaterinburg => **Asia/Yekaterinburg**
(GMT+05:00) Islamabad => **Asia/Karachi**
(GMT+05:00) Karachi => **Asia/Karachi**
(GMT+05:00) Tashkent => **Asia/Tashkent**
(GMT+05:30) Chennai => **Asia/Kolkata**
(GMT+05:30) Kolkata => **Asia/Kolkata**
(GMT+05:30) Mumbai => **Asia/Kolkata**
(GMT+05:30) New Delhi => **Asia/Kolkata**
(GMT+05:45) Kathmandu => **Asia/Kathmandu**
(GMT+06:00) Almaty => **Asia/Almaty**
(GMT+06:00) Astana => **Asia/Dhaka**
(GMT+06:00) Dhaka => **Asia/Dhaka**
(GMT+06:00) Novosibirsk => **Asia/Novosibirsk**
(GMT+06:00) Sri Jayawardenepura => **Asia/Colombo**
(GMT+06:30) Rangoon => **Asia/Rangoon**
(GMT+07:00) Bangkok => **Asia/Bangkok**
(GMT+07:00) Hanoi => **Asia/Bangkok**
(GMT+07:00) Jakarta => **Asia/Jakarta**
(GMT+07:00) Krasnoyarsk => **Asia/Krasnoyarsk**
(GMT+08:00) Beijing => **Asia/Hong\_Kong**
(GMT+08:00) Chongqing => **Asia/Chongqing**
(GMT+08:00) Hong Kong => **Asia/Hong\_Kong**
(GMT+08:00) Irkutsk => **Asia/Irkutsk**
(GMT+08:00) Kuala Lumpur => **Asia/Kuala\_Lumpur**
(GMT+08:00) Perth => **Australia/Perth**
(GMT+08:00) Singapore => **Asia/Singapore**
(GMT+08:00) Taipei => **Asia/Taipei**
(GMT+08:00) Ulaan Bataar => **Asia/Irkutsk**
(GMT+08:00) Urumqi => **Asia/Urumqi**
(GMT+09:00) Osaka => **Asia/Tokyo**
(GMT+09:00) Sapporo => **Asia/Tokyo**
(GMT+09:00) Seoul => **Asia/Seoul**
(GMT+09:00) Tokyo => **Asia/Tokyo**
(GMT+09:00) Yakutsk => **Asia/Yakutsk**
(GMT+09:30) Adelaide => **Australia/Adelaide**
(GMT+09:30) Darwin => **Australia/Darwin**
(GMT+10:00) Brisbane => **Australia/Brisbane**
(GMT+10:00) Canberra => **Australia/Sydney**
(GMT+10:00) Guam => **Pacific/Guam**
(GMT+10:00) Hobart => **Australia/Hobart**
(GMT+10:00) Melbourne => **Australia/Melbourne**
(GMT+10:00) Port Moresby => **Pacific/Port\_Moresby**
(GMT+10:00) Sydney => **Australia/Sydney**
(GMT+10:00) Vladivostok => **Asia/Vladivostok**
(GMT+11:00) Magadan => **Asia/Magadan**
(GMT+11:00) New Caledonia => **Asia/Magadan**
(GMT+11:00) Solomon Is. => **Asia/Magadan**
(GMT+12:00) Auckland => **Pacific/Auckland**
(GMT+12:00) Fiji => **Pacific/Fiji**
(GMT+12:00) Kamchatka => **Asia/Kamchatka**
(GMT+12:00) Marshall Is. => **Pacific/Fiji**
(GMT+12:00) Wellington => **Pacific/Auckland**
(GMT+13:00) Nuku\alofa => **Pacific/Tongatapu**
Whether the created schedule should be saved as template.
```bash curl theme={null}
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
}'
```
```JavaScript JavaScript theme={null}
fetch('https://dedi.emailbison.com/api/campaigns/{campaign_id}/schedule', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: 'Bearer YOUR_SECRET_TOKEN'
},
body: JSON.stringify({
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
})
})
```
```Python Python theme={null}
import requests
url = "https://dedi.emailbison.com/api/campaigns/%7Bcampaign_id%7D/schedule"
payload = {
"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
}
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_SECRET_TOKEN"
}
response = requests.post(url, json=payload, headers=headers)
```
### Campaign Sequence
The sequence of the campaign is the emails that will be sent out.
To create your sequence, send a `POST` request to `/api/campaigns/{campaign_id}/sequence-steps`.
The request can take only 2 fields in the body JSON. `title` and `sequence_steps`.
`title` is a string, and `sequence_steps` is an array that contains the following fields:
The title of the sequence
The subject of the email. To include variables, type in them in uppercase and wrap them with curly braces.
Note that these variables must exist as custom variables in your workspace.
Example: `"This is an email subject with a {VARIABLE}."`
The body of the email. To include variables, type in them in uppercase and wrap them with curly braces.
Note that these variables must exist as custom variables in your workspace.
Example: `"This is an email body with a {VARIABLE}."`
How many days before the sequence moves to the next step.
Whether the step is a variant
Required if `variant` is true.
The ID of the step this step is a variant of. You can get the step IDs with a `GET` request to \`/api/campaigns//sequence-steps.
Whether the step should be a reply from the previous step.
The request will look like the following example:
```bash curl theme={null}
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": "test sequence",
"sequence_steps": [
{
"email_subject": "Hey {FIRST_NAME}",
"order": 1,
"email_body": "You should check this {PRODUCT] out!",
"wait_in_days": 1,
"variant": true,
"variant_from_step": 223
},
{
"email_subject": "EmailBison is awesome!",
"order": 2,
"email_body": "Try it now!",
"wait_in_days": 1,
"variant": true,
"variant_from_step": 1,
"thread_reply": true
}
]
}'
```
```JavaScript JavaScript theme={null}
fetch('https://dedi.emailbison.com/api/campaigns/{campaign_id}/sequence-steps', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_SECRET_TOKEN'
},
body: JSON.stringify({
'title': 'test sequence',
'sequence_steps': [
{
'email_subject': 'Hey {FIRST_NAME}',
'order': 1,
'email_body': 'You should check this {PRODUCT] out!',
'wait_in_days': 1,
'variant': true,
'variant_from_step': 223
},
{
'email_subject': 'EmailBison is awesome!',
'order': 2,
'email_body': 'Try it now!',
'wait_in_days': 1,
'variant': true,
'variant_from_step': 1,
'thread_reply': true
}
]
})
});
```
```Python Python theme={null}
import requests
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_SECRET_TOKEN',
}
json_data = {
'title': 'test sequence',
'sequence_steps': [
{
'email_subject': 'Hey {FIRST_NAME}',
'order': 1,
'email_body': 'You should check this {PRODUCT] out!',
'wait_in_days': 1,
'variant': True,
'variant_from_step': 223,
},
{
'email_subject': 'EmailBison is awesome!',
'order': 2,
'email_body': 'Try it now!',
'wait_in_days': 1,
'variant': True,
'variant_from_step': 1,
'thread_reply': True,
},
],
}
response = requests.post(
'https://dedi.emailbison.com/api/campaigns/{campaign_id}/sequence-steps',
headers=headers,
json=json_data,
)
```
### Launching Campaign
After creating a campaign, updating its settings, creating or choosing a schedule, and creating a sequence, you have completed all the necessary steps in creating a campaign.
You can send these requests to check the details of a campaign:
* `GET /api/campaigns/{campaign_id}`: retrieves the campaign you created and its settings.
* `GET /api/campaigns/{campaign_id}/schedule`: retreives the campaign schedule.
* `GET /api/campaigns/{campaign_id}/sequence-steps`: retrieves the campaign sequences steps.
**Once you're ready to launch your campaign, send a `PATCH` request to `/api/campaigns/{campaign_id}/resume`.**
You can pause the campaign by sending a `PATCH` request to `/api/campaigns/{campaign_id}/pause`.
# Overview
Source: https://docs.emailbison.com/campaigns/overview
Campaigns orchestrate the emails that will be sent, who they will be sent to, and when they will be sent.
## Campaign Scheduler
The campaign scheduler will run and schedule emails to be sent out every time the campaign is resumed, as well as at the end of every sending day for the campaign.
If you need to manually run the campaings scheduler before the end of the sending day, you can pause and resume the campaign.
## Smart Scheduling
EmailBison uses a smart scheduling pattern to avoid automation detection. Campaign emails are sent on a random pattern throughout your sending window -- decided by the campaign's `schedule`.
## ESP Matching
EmailBison takes an unopinionated approach to ESP matching.
It is left to the user to decide if ESP matching or mis-matching is better for their deliverablity.
EmailBison provides you with the tools to achieve this by tagging every [lead](/leads/overview#esp-tagging) with their ESP.
## Relationship between Leads and Sender Emails
Once a lead has been sent an email in a campaign, the same Sender Email will send the remaining steps for that lead, as well as emails sent to the lead from a followup campaign.
# Adding Sender Emails
Source: https://docs.emailbison.com/email-accounts/adding-accounts
## Bulk Uploading
There are multiple ways to bulk upload accounts to EmailBison.
### Custom SMTP Providers (Emails not with Microsoft or Google)
Send a `POST` request to the [following endpoint](https://dedi.emailbison.com/api/reference#tag/email-accounts/post/api/sender-emails/imap-smtp).
```bash theme={null}
/api/sender-emails/imap-smtp
```
The `Content-Type` header key should be set to `multipart/form-data`.
The only parameter you must provide out is `csv`, and the value should be your CSV file.
An example of this request:
```bash curl theme={null}
curl https://dedi.emailbison.com/api/sender-emails/bulk \
--request POST \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data "{"csv":""}"
```
```JavaScript JavaScript theme={null}
fetch('https://dedi.emailbison.com/api/sender-emails/bulk', {
method: 'POST',
headers: {
'Content-Type': 'multipart/form-data',
Authorization: 'Bearer YOUR_SECRET_TOKEN'
},
body: '{'csv':''}'
})
```
```Python Python theme={null}
url = 'https://dedi.emailbison.com/api/sender-emails/bulk'
payload = {'csv':'csv'}
headers = {
'Content-Type': 'multipart/form-data',
'Authorization': 'Bearer YOUR_SECRET_TOKEN'
}
response = requests.post(url, data=payload, headers=headers)
print(response.json())
```
Navigate to `Email Accounts` -> `Connect Email Account` -> `Bulk Upload Custom Provider`
Download and refer to the sample CSV file for proper CSV formatting.
***
### Microsoft Accounts
The EmailBison team has built and released a native program to bulk upload Microsoft accounts.
The download and all instructions can be found on the [Bulk Uploader Tool](/email-accounts/bulk-uploader-tool) page.
### Google Accounts
Bulk uploading Google accounts is currently not first-party supported due to the frequent captcha requirements by Google.
# Changelog
Source: https://docs.emailbison.com/email-accounts/bulk-uploader-tool/changelog
Bulk Uploader Tool Changelog
## EmailGuard Compatibility; Tagging Fix
* Updated EmailGuard mode to work on new layout.
* Added new flag `--emailguard-prompt-login` and the equivalent advanced option.
* Intended for advanced usage, in almost all cases this should be left as `false / no`.
* Fixed issue causing email tagging to not correctly trigger.
## Support for Admin Consent Prompt
* This update is required for the new EmailBison "Admin Consent Prompt" Option. Backwards compatibility is maintained.
* You can now provide an optional `use_as_admin` column in your CSV file, which will cause the uploader to check "Admin Consent Prompt" on the EmailBIson Page.
* Fixed issue with workspace name not being read properly.
* Stability Improvements.
## Minor maintenance patch.
* This update is a minor maintenance patch.
## Minor enhancements.
* The tool has better selectors for the EmailBison connect page. This update is needed in cases where the layout has changed.
* Fixed an issue where the tool would say the API key is not correct for the workspace, when it is.
## Minor enhancements.
* Will now stop on wrong Microsoft username in `rod` driver.
* Will now display account timeouts ("context deadline exceeded") as failures.
* Explained the "context deadline exceeded" error.
## Minor bug fixes.
* Fixed edge case in `rod` driver where microsoft password page would time out.
* The average time per account display was rounded, it now displays with 2 decimal places.
* Fixed wording for `--help` flag output.
## GUI Overhaul. New Driver. Flag Options in GUI.
This update is a large overhaul of the tool, read below to learn what's been changed:
![]()
#### What's new:
* Brand-new user interface (see image above)! The interface looks more pleasing, offers more functionality, and is easier to use.
* You can now set any flag option directly from the GUI just by following the prompts, you can skip learning how to launch the tool from the terminal and pass flags!
* Users who choose to use flags have not been forgotten. Interaction flags have been deprecated for a more intuitive `--non-interactive` flag! This flag removes all input prompts and allows you to integrate the tool with your other automations painlessly. The list of deprecated flags can be found at the end of these update notes.
* Only failures will now be printed to the terminal, and to supplement this, you will have a running count of processed accounts, successful accounts, and failed accounts. This will reduce noise output and help you identify at a glance which accounts failed.
* The output CSV file will now only include failures. This allows you to re-run only failed accounts without an API key, by running the tool again on the output file.
* A new "driver" (the tech that controls the browsers) has been introduced, with promising internal testing. The new driver is selected by default. Users can opt for the old driver either from the GUI or by passing in a `--driver` flag.
#### Deprecated features and flags
The "reconnect existing accounts" prompt and flag have both been removed. This setting has been replaced by the "skip connected accounts if they exist" setting, which will still sign in to existing accounts in a disconnected state, which is a better workflow.
The following flags have been removed in favor of the intuitive `--non-interactive` flag.
* `--skip-api-key-warning`
* `--skip-workspace-prompt`
The following flag has been removed.
* `--connect-existing-accounts`
#### Behaviour Changes
The following flag has been renamed, and changed to a boolean, `false` by default.
* ~~`--connect-disconnected-accounts-only`~~ => `--skip-connected-accounts`
#### Bug fixes
* Fixed `Ctrl+C` behaviour. You should be able to hit `Ctrl+C` at any time to stop the tool without unexpected behaviour.
* Fixed incomplete CSV output, and accounts not being tagged, if the tool is stopped before processing all accounts.
* Fixed a case where failures on accounts would have an empty message.
* Fixed dragging a CSV file on the tool causing issues if flags were passed.
* Fixed edge case where user was still prompted when the non-interactive flags were passed.
## V2 support. New features. Improved success rate.
The EmailBison Bulk Uploader has been improved and many new features have been added.
What's new:
* The tool is updated to work on the EmailBison v2 beta! The tool will auto detect if it should run on v1 or v2 EmailBison, or EmailGuard.
* New feature: only process accounts that are "not connected" on EmailBison (requires API key).
* New feature (beta): You can now drop csv files directly into the executable instead of picking from the file picker.
* Many bug fixes, resulting in much higher success rate.
Tested with --browsers 20 (spawning 20 browsers at once instead of the default 6), when RAM was fully used and macbook had to use swap for all new browsers, 100% success rate.
* Better error messages all around -- no more "SMTP error", instead, you get the EmailBison error, such as "Email already exists on another workspace: John's Team".
* New flags added (run the tool with -help from the terminal to see all flags):
* `csv-file` -- \[interaction] specify a path to a csv file to skip file picker prompt, works like the `config-file` flag.
* `skip-workspace-prompt` -- \[interaction] skips prompt for confirming the workspace.
* `skip-api-key-warning` -- \[interaction] skips prompt for continuing without an API key.
* `connect-existing-accounts` -- \[interaction] skips prompt by answering in advance whether to connect existing accounts.
* `connect-disconnected-accounts-only` -- \[interaction] skips prompt by answering in advance whether to connect disconnected accounts only.
* `force-bison-v1` -- forces tool into EmailBison v1 mode, if auto-detection fails.
* `force-bison-v2` -- forces tool into EmailBison v2 mode, if auto-detection fails.
The \[interaction] flags will allow the tool to run without any user input.
# Overview
Source: https://docs.emailbison.com/email-accounts/bulk-uploader-tool/overview
The EmailBison team provides executables for uploading Microsoft accounts to EmailBison on Windows, macOS, and Linux .
The latest version of the tool can be downloaded here:
The executable for Windows
The binary for macOS
The binary for Linux
Your browser could block this download. Right click on one of the cards and click `Save as` or `Save link as`.
## Using the tool
In the zip file you downloaded, you will find instructions on using the tool in `how_to_use.txt`.
Alternatively, you can watch a walkthrough of using the tool in action:
## Issues and FAQs
### Common Issues When Launching
This is a common macOS issue depending on how your mac is set up.
To fix this, follow [these short steps from Apple](https://support.apple.com/en-ca/guide/mac-help/mh40616/mac)
This is a common issue with macOS GateKeeper quarantining files downloaded from unknown sources.
To fix this, enter the following in your terminal:
```bash theme={null}
xattr -c path/to/emailbison_bulk_uploader
```
Where `path/to/emailbison_bulk_uploader` is the path to the EmailBison tool.
This is a common issue due to default settings on Micsorosft SmartScreen.
To fix this, click on `More info` -> `Run anyway`.
Microsoft blocks .exe files downloaded from the internet
To fix this, right click the program, click on `properties`, towards the end, there's a **Security:** label with an `Unblock` checkbox, check it and press `OK`.
### Common Issues While Using the Script
Most set-up issues are self-reporting and the issue will be shown in your terminal.
Common issues include:
* Not having config.txt in the same place as the program.
* Not populating config.txt.
* Providing the wrong URL or wrong credentials in config.txt.
* Your CSV headers are not "name, email, password".
* Manual Resolution:
1. Refer to [this help article](https://help.bisonsphere.com/en/articles/205-microsoft-need-admin-approval) to resolve this manually.
* Automatic resolution:
1. For each different tenant in the CSV, include 1 account with the "Cloud Applications Admin" role.
2. include a "use\_as\_admin" column, mark the row this account is in as true.
3. The bulk uploader will now login to the admin marked accounts first, and attempt to accept permissions tenant-wide.
4. The rest of the accounts will work now that the permissions are granted.
### Advanced Usage
The walkthrough above is enough for most use-cases.
However, the bulk uploader tool can be fine-tuned to specific needs with flags.
Flags are arguments you pass in the command line, you can watch the following video for a quickstart.
#### Flags available
These are the flags available. You can use the flag `--help` to see these flags in your terminal.
| Flag | Type | Description | Default | Example |
| ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------- | ------------------------------------------- |
| non-interactive | boolean | Disable all prompts and inputs. Still outputs info to the terminal. `--csv-file` flag required with this flag | false | `--non-interactive` |
| browsers | integer | How many browsers to spawn concurrently | **6**, min: 1, max: 16 | `--browsers 4` |
| no-headless | boolean | spawns visible browsers. Use `--browsers 1` with this flag | false | `--no-headless` |
| timeout | integer | How long, in seconds, before treating the email as a fail and moving on. Useful to change on very slow connections | **75**, min: 30, max: 180 | `--timeout 180` |
| tag | string | What to tag this batch of emails (will create tag if it doesn't exist) | "" | `--tag "batch 1"` |
| skip-connected-accounts | boolean | If account exists on EmailBison, and is in a "connected" state, skip it. | false | `--skip-connected-accounts` |
| config-file | string | Use a custom config file, you can also provide the path if in another directory | "config.txt" | `--config-file "../configs/workspace4.txt"` |
| csv-file | string | A path to the csv file to use, to skip the file picker prompt. | "" | `--csv-file "../files/accounts.csv"` |
| throttle | boolean | Use recommended throttling to avoid issues of the script signing in to accounts too fast | false | `--throttle` |
| driver | string | The technology that controls the browsers. Either "rod" or "chromedp" | "rod" | `--driver rod` |
# Overview
Source: https://docs.emailbison.com/email-accounts/overview
Sender Emails are the email accounts EmailBison will use to send emails from.
EmailBison provides unlimited storage for sender emails. If you are connecting a large amount of accounts, please contact the EmailBison support team to ensure that your private infrastructure is scaled up.
## Sender Email Types
EmailBison separates sender emails into three types:
1. Google Accounts
2. Microsoft Accounts
3. Custom SMTP Accounts
You can have all three types connected to a workspace, and even attached to the same campaign.
## Workspace Interactions
Sender Emails are the only record that can only exist in one workspace at a time. You can not connect the same sender email to multiple workspaces.
# API Authentication
Source: https://docs.emailbison.com/get-started/authentication
## API Keys
EmailBison uses Bearer tokens to authenticate requests. You can create tokens by visiting `Settings` -> `Developer API` -> `New API Token`.
There are two types of tokens (keys) you can create.
1. `api-user` tokens only authenticate for the workspace they were created in. Each workspace will need a separate token.
2. `super-admin` tokens impersonate the user that created them. While they can only be scoped to one workspace at a time, the workspace they are scoped to will change if the user changes their workspace.
It is recommended to use `api-user` keys. They are simpler to manage, and generally offer the same permissions.
## Authorization
All API requests should include your API key in an Authorization HTTP header as follows:
`Authorization: Bearer YOUR_API_KEY`
Where `Authorization` is the Key in your header, and `Bearer YOUR_API_KEY` is the Value.
An example of a request that is properly authenticated:
```bash curl theme={null}
curl https://dedi.emailbison.com/api/users \
--header 'Authorization: Bearer 9|q8kSmhjJRqJVT2kc1M0ezX640Pxk'
```
```JavaScript JavaScript theme={null}
fetch('https://dedi.emailbison.com/api/users', {
headers: {
Authorization: 'Bearer 9|q8kSmhjJRqJVT2kc1M0ezX640Pxk'
}
})
```
```Python Python theme={null}
url = "https://dedi.emailbison.com/api/users"
headers = {"Authorization": "Bearer 9|q8kSmhjJRqJVT2kc1M0ezX640P"}
response = requests.get(url, headers=headers)
```
# Introduction
Source: https://docs.emailbison.com/get-started/introduction
Welcome to the EmailBison Docs
This documentation aims to get you started on using the robust EmailBison API.
This documentation is not meant as a replacement to the [API Reference](https://dedi.emailbison.com/api/reference), rather, it aims to supplement it. It will go over common workflows, and show the API calls to achieve them.
## Using this documentation
This documentation is separated into categories, which have pages on common workflows when using EmailBison.
Pages will have subsections, which can easily be navigated to from the navigation menu on the right side of each page.
Keep an eye out for tabs that are on many pages, they will provide alternate workflows, text and video versions, as well as API and UI versions.
This tab will have the API version.
This tab will have the UI version.
If you are less familiar with APIs, need a refresher, or there are some terms used in this documentation that need explaining, visit [Quickstart](/get-started/quickstart/making-http-requests).
If you are mainly interacting with the EmailBison APIs through a low-code tool, such as Clay, Zapier, or Make, visit [Low-Code Tools](/low-code-tools/introduction) to supplement the API calls found throughout this documentation.
# Pagination
Source: https://docs.emailbison.com/get-started/pagination
Some API requests will retrieve a large dataset. To ensure proper handling of this data, EmailBison will paginate the response.
This essentially means that you will receive chunks, or pages, of the data.
The response will be broken up into pages of 15 data entries per page, with information on how to view the next chunk.
For example, a `GET` request at the endpoint `/api/leads` will always be paginated, as there could be thousands of entries in leads.
Paginated responses from the API will have a `data` field for the entries at this page, as well as `links` and `meta` fields that provide you with information about the pagination in the response.
```json 200 {17-28} theme={null}
{
"data": [
{
"id": 835910,
"first_name": "John",
"last_name": "Doe",
"email": "JohnDoe@email.com",
},
{
"id": 835898,
"first_name": "Jane",
"last_name": "Doe",
"email": "JaneDoe@email.com",
},
... +13 Leads
],
"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,
...Extra information truncated
}
}
```
## Retrieving the data programmatically
Send a request to your desired paginated endpoint.
After processing the data received, you would then send a request to the endpoint provided at `links.next` in the response, if it is **not** `null`.
Alternatively, you could loop the query by adding the page number as a paremeter for your request, incrementing the page number until you reach `meta.last_page`.
This looks like `YOUR_URL.com/api/leads?page={page_number}`, where `{page_number}` is incremented by 1 each time until you reach `meta.last_page`.
## Retrieving a specific page
Add a query paramter to the end of your request with the page number.
This looks like `YOUR_URL.com/api/leads?page={page_number}`, where `{page_number}` is the page you would like to retrieve.
## Cursor Pagination vs Default Page Pagination
The main difference between the two is that `cursor` pagination lets you traverse data much faster than the traditional page based pagination.
If you or your team is requesting large amounts of data to loop through, we recommend using cursor pagination.
Traditional page based pagination is automatically limited to 1000 pages for all `index` routes (eg `/api/leads`, `/api/replies`, etc.). For larger datasets, use cursor pagination.
#### How does cursor pagination work?
When using cursor pagination, pass in an extra query parameter called `pagination_type` set to `cursor`.
This will instruct the API to return the response with values for the `next_cursor` and `prev_cursor`.
Think of a cursor as a "pointer," where each dataset belongs to a cursor. To request the next page, your request will need to contain that page's cursor.
#### Example
Request the first page of leads and set `pagination_type` to `cursor`:
`YOUR_URL.com/api/leads?pagination_type=cursor`
You'll get your list of leads along with the following `meta` info:
```json theme={null}
"meta": {
"path": "https://dedi.emailbison.com/api/leads",
"per_page": 15,
"next_cursor": "eyJpZCI6NzQ1NjAsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
"prev_cursor": null
}
```
To request the next page, pass the `next_cursor` value as the `cursor` query parameter:
`YOUR_URL.com/api/leads?pagination_type=cursor&cursor=eyJpZCI6NzQ1NjAsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0`
That page will then return a `meta` object containing cursors for both the previous and next page:
```json theme={null}
"meta": {
"path": "https://dedi.emailbison.com/api/leads",
"per_page": 15,
"next_cursor": "eyJpZCI6NzQ1NDUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
"prev_cursor": "eyJpZCI6NzQ1NTksIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9"
}
```
Continue using the `next_cursor` value from each response as the `cursor` query parameter on your next request to traverse the full dataset.
# Making API Requests
Source: https://docs.emailbison.com/get-started/quickstart/making-http-requests
It is recommended to familiarize yourself with making one-off requests to the API to test the endpoints and their responses.
EmailBison provides you with an API reference page that allows you to test any of the available endpoints by clicking the `Test Request` button. You can access this page by navigating to `Settings` -> `Developer API` -> `Full API Reference`.
Alternatively, You can use tools such as [Postman](https://postman.com) to make these requests, as you can import the *curl* requests from the examples provided throughout these docs.
# Notes and Terminology
Source: https://docs.emailbison.com/get-started/quickstart/notes-and-terminology
## Endpoint / URL
Throughout this documentation, you will see endpoint URLs formatted such as:
```bash theme={null}
/api/tags/attach-to-leads
```
This is not the full URL, as each user will have a different base URL to prepend.
The base URL of endpoints will be the same URL you use to log in to EmailBison. For example, if you log in to `https://send.greenmarketing.com`, then the preceding request should be made to:
```bash theme={null}
https://send.greenmarketing.com/api/tags/attach-to-leads
```
## Path, Query, and Body Parameters
There are three (four including headers) types of parameters:
* Path Parameters
* Query Parameters
* Body Parameters
The majority of parameters will be body parameters. These are parameters sent in the body of a request, in the form of JSON.
Path parameters are part of the URL, seperated by slashes. They are straight-forward and easy to spot.
Query parameters are appended to a URL, starting with a `?` sign.
### Path Parameters
In this documentation, these are represented as part of the endpoint, wrapped in `{}` brackets.
An example of a `campaign_id` path parameter-- is in the following endpoint:
```bash theme={null}
GET /api/campaigns/{campaign_id}
```
Path parameters have to be substituted, including the surrounding `{}` brackets, with the variable they represent, usually an ID.
For this example, a correct request would be made to:
```bash theme={null}
/api/campaigns/27
```
### Query Parameters
For convenience, EmailBison will convert body parameters into query parameters automatically, if the parameter names match.
These parameters are used in `GET` requests. They can be appended directly to the URL, or handled by the tool you are using to send requests.
If appended to the URL, you must add a question mark -- `?` -- and then your query parameters, separated by an ampersand -- `&`.
The following is an example of a request containing `folder: inbox` and `status: interested` query parameters.
```
/api/replies?folder=inbox&status=interested
```
For arrays, such as `tag_ids`, pass the array entries using the following syntax.
```
/api/replies?tag_ids[]=1&tag_ids[]=2&tag_ids[]=3
```
This request will send an array of `tag_ids = [1, 2, 3]`.
### Body Parameters
EmailBison uses the JSON data format for body parameters, unless the request will include a file, then it will use Form Data.
JSON body parameters will look like the following example.
```json theme={null}
{
"name": "John",
"email": "john@email.com",
"company": "EmailBison",
"custom_variables": [
{
"name": "phone_number",
"value": "123-456-7890"
}
]
}
```
# SCIM Provisioning
Source: https://docs.emailbison.com/get-started/scim
To request access to SCIM, you must be on an enterprise plan. Please contact us via your dedicated slack channel
## What is SCIM?
SCIM (System for Cross-domain Identity Management) is an open standard (RFC 7643/7644) that lets your identity provider (IdP) (such as Okta, Microsoft Entra ID, or OneLogin) automatically manage user accounts in EmailBison.
Instead of creating, updating, and removing accounts by hand, your IdP keeps them in sync for you. It handles:
* **Provisioning** - when you assign a person to the app in your IdP, an account is created here automatically
* **Updates** - profile changes (name, email) made in your IdP flow through to their account
* **Group sync** - groups in your IdP are mirrored as teams, and membership stays in sync
* **Deprovisioning** - when someone leaves your organization or is unassigned, their account is deactivated automatically, closing access immediately
SCIM works alongside SSO: SSO handles *authentication* (signing in), while SCIM handles the *lifecycle* of the account itself.
## Base URL
`https://your-app.example.com/api/scim/v2`
## Authentication
All requests must include a bearer token in the `Authorization` header.
Authorization: `Bearer `
You can generate a SCIM token from your account settings. Treat it like a password - it grants full provisioning access.
## Supported endpoints
### Users
| Method | Endpoint | Description |
| ------ | ------------- | ----------------------------------------------------- |
| GET | `/Users` | List users. Supports *filter*, *startIndex*, *count*. |
| POST | `/Users` | Create a user. |
| GET | `/Users/{id}` | Retrieve a single user. |
| PUT | `/Users/{id}` | Replace a user's attributes. |
| PATCH | `/Users/{id}` | Partially update a user (e.g. deactivate). |
| DELETE | `/Users/{id}` | Delete a user. |
### Groups
| Method | Endpoint | Description |
| ------ | -------------- | ------------------------------------------------------ |
| GET | `/Groups` | List groups. Supports *filter*, *startIndex*, *count*. |
| POST | `/Groups` | Create a group. |
| GET | `/Groups/{id}` | Retrieve a single group. |
| PUT | `/Groups/{id}` | Replace a group, including its full member list. |
| PATCH | `/Groups/{id}` | Partially update a group (add/remove members, rename). |
| DELETE | `/Groups/{id}` | Delete a group. |
### Discovery
| Method | Endpoint | Description |
| ------ | ------------------------ | ------------------------------------------------- |
| GET | `/ServiceProviderConfig` | Describes supported SCIM features. |
| GET | `/ResourceTypes` | Lists available resource types (*User*, *Group*). |
| GET | `/Schemas` | Lists supported SCIM schemas. |
## Notes
* Groups in your IdP map to teams in the application.
* Filtering supports the equality form, e.g. `filter=userName eq "jane@example.com"`.
* Deactivating a user (`active: false`) immediately blocks access; the account and its data are retained until deleted.
* Requests and responses use the `application/scim+json` content type.
# Single Sign-On (SSO) with SAML 2.0
Source: https://docs.emailbison.com/get-started/sso
## What is SAML SSO?
SAML 2.0 (Security Assertion Markup Language) is an industry-standard protocol that lets your team sign in to EmailBison using your company's existing identity provider (such as Microsoft Entra ID (Azure AD), Okta, Google Workspace, OneLogin, or JumpCloud) instead of a separate username and password.
In SAML terms, your identity provider (IdP) vouches for who your users are, and EmailBison acts as the service provider (SP) that trusts those assertions.
## Why use it?
One less password - your team signs in with the company credentials they already use every day.
Centralized access control - grant or revoke access to EmailBison directly from your identity provider. When someone leaves your organization, disabling their IdP account removes their access.
Your security policies apply - multi-factor authentication, device policies, and conditional access rules enforced by your IdP automatically apply to EmailBison.
Automatic account creation - new team members get an EmailBison account the first time they sign in. No manual invitations needed.
## How signing in works
A user visits their organization's dedicated sign-in link, e.g. `https://app.example.com/sso/emailbison`.
They're redirected to your identity provider's familiar sign-in page.
Your IdP verifies their identity (including any MFA your organization requires).
The IdP sends a signed, encrypted assertion back to EmailBison confirming who they are.
They're signed in and land in EmailBison within a couple of seconds.
If your team uses an app dashboard (like the Okta home page or the Microsoft 365 app launcher), users can also start from there: clicking the EmailBison tile signs them straight in.
## How signing out works
Signing out of EmailBison ends the EmailBison session. If your organization enables SAML Single Logout (SLO), signing out can also end the session at your identity provider, so a shared or public computer isn't left signed in elsewhere.
We'll configure this with you based on your preference during setup.
## What we'll need from you
Setup takes about 15 minutes with your IT administrator:
You send us your identity provider's metadata URL (or metadata XML file). Your IT admin can find this in your IdP's admin console. For example, Entra ID calls it the "App Federation Metadata URL," and Okta shows it under the application's Sign On tab.
We send you back our service provider details (Entity ID, ACS URL, and metadata) to paste into your IdP's application settings.
We run a test sign-in together, then enable it for your whole team.
## Get started
To get your organization connected, please contact us via your dedicated slack channel
# Adding Leads
Source: https://docs.emailbison.com/leads/creating-a-lead
You can add leads one at a time using the API, or bulk add leads in a CSV file using the UI or the API.
## Adding Single Leads
You can create a single lead by sending a `POST` request at the [following endpoint](https://dedi.emailbison.com/api/reference#tag/leads/post/api/leads).
```bash theme={null}
/api/leads
```
The required fields are `first_name`, `last_name`, and `email`.
The optional fields are `title`, `company`, `notes`, and [`custom variables`](/leads/custom-variables).
Custom variables need to be created in advance in each workspace.
The following is an example of creating a single lead:
```bash curl theme={null}
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": "John Doe Company",
"notes": "Important client",
"custom_variables": [
{
"name": "phone number",
"value": "9059999999"
}
]
}'
```
```JavaScript JavaScript theme={null}
fetch('https://dedi.emailbison.com/api/leads', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: 'Bearer YOUR_SECRET_TOKEN'
},
body: JSON.stringify({
first_name: 'John',
last_name: 'Doe',
email: 'john@doe.com',
title: 'Engineer',
company: 'John Doe Company',
notes: 'Important client',
custom_variables: [{
name: 'phone number',
value: '9059999999'
}]
})
})
```
```Python Python theme={null}
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_SECRET_TOKEN',
}
json_data = {
'first_name': 'John',
'last_name': 'Doe',
'email': 'john@doe.com',
'title': 'Engineer',
'company': 'John Doe Company',
'notes': 'Important client',
'custom_variables': [
{
'name': 'phone number',
'value': '9059999999',
},
],
}
response = requests.post('https://dedi.emailbison.com/api/leads', headers=headers, json=json_data)
```
## Bulk Uploading Leads
Do **not** set the `content-type` header for this request.
It will be automatically set to `multipart/form-data` because of the file included.
Bulk upload leads with a `POST` request to the following endpoint.
```bash theme={null}
/api/leads/bulk/csv
```
The request takes the following fields:
The name of the lead list that will be created
The CSV file.
The name of the CSV header column that corresponds to `first_name` on EmailBison
The name of the CSV header column that corresponds to `last_name` on EmailBison
The name of the CSV header column that corresponds to `email` on EmailBison
The remaining fields you would like to map - including custom variables - each getting their own field.
The following is an example of a request to bulk upload a CSV file:
```Bash curl theme={null}
curl https://dedi.emailbison.com/api/leads/bulk/csv \
--request POST \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data "{
"name":"John Does list",
"csv":"/Users/Jack/Desktop/list.csv",
"columnsToMap[0][first_name]":"name",
"columnsToMap[0][last_name]":"last name",
"columnsToMap[0][email]":"email",
"columnsToMap[0][company]":"company name",
"columnsToMap[0][my_custom_variable]":"my_custom_variable"
}"
```
```JavaScript JavaScript theme={null}
let formData = new FormData();
formData.append('file', fs.createReadStream('/Users/Jack/Desktop/list.csv'));
formData.append('name', 'John Does List');
formData.append('columnsToMap[0][first_name]', 'name');
formData.append('columnsToMap[0][last_name]', 'last name');
formData.append('columnsToMap[0][email]', 'email address');
formData.append('columnsToMap[0][company]', 'company name');
formData.append('columnsToMap[0][my_custom_variable]', 'my custom variable');
fetch("https://dedi.emailbison.com/api/leads/bulk/csv",
{
body: formData,
method: "POST"
});
})
```
```Python Python theme={null}
url = 'https://dedi.emailbison.com/api/leads/bulk/csv'
fp = '/Users/Jack/Desktop/list.csv'
files = {'file': open(fp, 'rb')}
payload = {
'name': 'my list'
'columnsToMap[0][first_name]':'name',
'columnsToMap[0][last_name]':'last name',
'columnsToMap[0][email]':'email',
'columnsToMap[0][company]':'company name',
'columnsToMap[0][my_custom_variable]':'my_custom_variable'
}
response = requests.post(url, files=files, data=payload)
```
## Bulk Uploading Leads
There is a 50,000 lead limit per CSV file
Navigate to `Contacts` -> `Import New Contacts`.
You can download and refer to the Sample CSV file on proper formatting.
# Custom Variables
Source: https://docs.emailbison.com/leads/custom-variables
A custom variable is EmailBisons way of attaching any extra information to a lead.
Custom Variables need to be created before they can be attached to leads with a custom value for each lead.
Note: custom variables are unique per workspace
## Creating Custom Variables
You can create a custom variable by submitting a `POST` request at the [following endpoint](https://dedi.emailbison.com/api/reference#tag/custom-lead-variables/post/api/custom-variables).
```bash theme={null}
/api/custom-variables
```
The only field you can and must provide is `name`, which is a name for the custom variable.
## Attaching Custom Variables to Leads
When you are creating or updating a lead - either with a `POST` or a `PUT` - you can pass the `custom_variables` field as an array of objects that contain a `name` key and a `value` key. The JSON will look like the following.
```json theme={null}
"custom_variables": [
{
"name": "phone_number",
"value": "123-456-7890"
},
{
"name": "priority",
"value": "super-high"
}
]
```
Note how the everything is wrapped in an array identifier `[]`, and each custom variable is wrapped in an object identifier `{}`
An example of adding custom variables when updating leads:
```Bash curl {9-14} theme={null}
curl https://dedi.emailbison.com/api/leads \
--request PUT \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"first_name": "John",
"last_name": "Doe",
"email": "john@doe.com",
"custom_variables": [
{
"name": "phone number",
"value": "9059999999"
}
]
}'
```
```JavaScript JavaScript {11-14} theme={null}
fetch('https://dedi.emailbison.com/api/leads/{lead_id}', {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
Authorization: 'Bearer YOUR_SECRET_TOKEN'
},
body: JSON.stringify({
first_name: 'John',
last_name: 'Doe',
email: 'john@doe.com',
custom_variables: [{
name: 'phone number',
value: '9059999999'
}]
})
})
```
```Python Python {10-15} theme={null}
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_SECRET_TOKEN',
}
json_data = {
'first_name': 'John',
'last_name': 'Doe',
'email': 'john@doe.com',
'custom_variables': [
{
'name': 'phone number',
'value': '9059999999',
},
],
}
response = requests.put('https://dedi.emailbison.com/api/leads/{lead_id}', headers=headers, json=json_data)
```
Refer to [Leads](/leads/creating-a-lead#ui) on uploading a CSV using the UI.
1. Include Custom Variables as columns in the CSV.
![an example of two custom variables, interests and phone_number]()
2. Once you upload the CSV, the UI will ask you to map your headers.
During this step, click on `Add custom variable`, enter a name for your variable and click the `+` button.
![Creating Custom Variables]()
3. After following the first and seconds steps, map your custom variables to the CSV headers.
For example, map the `phone number` custom variable to the `phone_number` CSV header.
![Mapping Custom Variables]()
# Overview
Source: https://docs.emailbison.com/leads/overview
Leads, also referred to as Contacts, are your potential email addresses being contacted as part of campaigns.
EmailBison provides unlimited storage for leads. However, CSVs and campaigns are limited to 50,000 leads at once.
## Updating Leads
Leads can be updated by uploading the same CSV with new values, provided the email address doesn't change.
This will also update them in-place in any campaigns they are in, without any further input from the user.
## Custom Variables
[Custom Variables](/leads/custom-variables) exist separately from leads, as just names, and each lead can have a value associated with any custom variable on a workspace.
They are unique to each workspace, and must be created in advance.
For example, you create the custom variable `linked_url` on a workspace. Each lead you upload in that workspace, you can attach any value for `linkedin_url`.
## ESP Tagging
Every lead uploaded to EmailBison will automatically be tagged with their ESP, to give you the choice of [ESP Matching](/campaigns/overview#esp-matching).
## Workspace Interactions
You can have the same lead (email address) in multiple workspaces. However, each lead will be unique, with a different ID. This essentially means that the same email address could have all the other fields (such as name, title, custom variables) be different in each workspace.
# Authenticating
Source: https://docs.emailbison.com/low-code-tools/clay/authenticating-requests
This page covers authentication for non-native requests using the `HTTP API` enrichment. If you're using [native EmailBison enrichments](/low-code-tools/clay/enrichments), authentication is handled automatically through your connected workspace accounts.
Requests to EmailBison need to be authenticated with an [API Key](/get-started/authentication).
You can either send a header with an `Authorization` key each time you add a new `HTTP API` enrichment, or you can save this header to your `accounts` so you can select it from a dropdown.
### Saving the headers to your accounts
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
If you have already done these steps, you can select an account from the dropdown under `Account` to authenticate requests in this column with.
1. In your Clay HTTP API enrichment, scroll down to `Account`.
2. Click `+ Add Account`.
3. Put in a friendly name, such as `EmailBison Workspace A`
4. Click `Add a new Key and Value pair`.
5. In the `Key` field, input `Authorization`.
6. In the `Value` field, input `Bearer YOUR_API_KEY` (the word Bearer, a space, and your [API Key](/get-started/authentication)).
7. Click `Save`.
8. You can now select this account from the `Accounts` dropdown for any future columns you add to your Clay workspace.
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
The following video will implement the text instructions on a Clay table.
***
### Manually authorizing each request
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
1. In your Clay HTTP API enrichment, scroll down to `Headers`.
2. Click `Add a new Key and Value pair`.
3. In the `Key` field, input `Authorization`.
4. In the `Value` field, input `Bearer YOUR_API_KEY` (the word Bearer, a space, and your [API Key](/get-started/authentication)).
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
The following video will implement the text instructions on a Clay table.
***
Once you've familiarilized yourself with how to authenticate your requests using Clay, visit [Clay - GET Requests](/low-code-tools/clay/get-requests) and [Clay - POST Requests](/low-code-tools/clay/post-requests) for instructions that will apply to the majority of API requests to EmailBison.
# Native Enrichments
Source: https://docs.emailbison.com/low-code-tools/clay/enrichments
The official EmailBison integration for Clay provides the following enrichments to streamline your workflow.
Make sure you've [connected your workspace](/low-code-tools/clay/workspace-setup) before using these enrichments.
* [Find Lead](/low-code-tools/clay/enrichments/find-lead) - Search for and retrieve lead information from your workspace
* [Create or Update Lead](/low-code-tools/clay/enrichments/create-or-update-lead) - Add new leads or update existing ones in your workspace
* [Import Lead(s) to Campaign](/low-code-tools/clay/enrichments/import-leads-to-campaign) - Add leads to your specific workspace campaigns
* [Add Email to Blocklist](/low-code-tools/clay/enrichments/add-email-to-blocklist) - Block specific email addresses from your workspace
* [Add Domain to Blocklist](/low-code-tools/clay/enrichments/add-domain-to-blocklist) - Block specific domains in your workspace
* [Remove Email from Blocklist](/low-code-tools/clay/enrichments/remove-email-from-blocklist) - Unblock previously blocked email addresses
* [Remove Domain from Blocklist](/low-code-tools/clay/enrichments/remove-domain-from-blocklist) - Unblock previously blocked domains
# Add Domain to Blocklist
Source: https://docs.emailbison.com/low-code-tools/clay/enrichments/add-domain-to-blocklist
Add domains to your EmailBison blocklist.
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
1. **Add the Enrichment**
* In your Clay table, click `+ Add column`
* Select `Enrichments`
* Search for and select `"Add domain to blocklist"`
2. **Select Your Workspace**
Choose your desired EmailBison account (workspace) from the dropdown.
If you don't see your workspace, click `+ Add account` and [connect your workspace](/low-code-tools/clay/workspace-setup).
3. **Map the Domain Column**
Under `Column mapping`, map the required column:
* `Domain` (required)
4. **Save and Run**
Save the enrichment and run the column to add all the domains in the domain column to the blocklist.
Set this column to auto-run if data updates elsewhere and you need your leads to be added or updated whenever new data flows in.
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
The following video will implement the text instructions on a Clay table.
# Add Email to Blocklist
Source: https://docs.emailbison.com/low-code-tools/clay/enrichments/add-email-to-blocklist
Add specific email addresses to your EmailBison blocklist.
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
1. **Add the Enrichment**
* In your Clay table, click `+ Add column`
* Select `Enrichments`
* Search for and select `"Add email to blocklist"`
2. **Select Your Workspace**
Choose your desired EmailBison account (workspace) from the dropdown.
If you don't see your workspace, click `+ Add account` and [connect your workspace](/low-code-tools/clay/workspace-setup).
3. **Map the Email Column**
Under `Column mapping`, map the required column:
* `Email` (required)
4. **Save and Run**
Save the enrichment and run the column to add all the emails in the email column to the blocklist.
Set this column to auto-run if data updates elsewhere and you need your leads to be added or updated whenever new data flows in.
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
The following video will implement the text instructions on a Clay table.
# Create or Update Lead
Source: https://docs.emailbison.com/low-code-tools/clay/enrichments/create-or-update-lead
Add new leads or update existing leads in your EmailBison workspace directly from your Clay table.
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
1. **Add the Enrichment**
* In your Clay table, click `+ Add column`
* Select `Enrichments`
* Search for and select `"Create or update lead"`
2. **Select Your Workspace**
Choose your desired EmailBison account (workspace) from the dropdown.
If you don't see your workspace, click `+ Add account` and [connect your workspace](/low-code-tools/clay/workspace-setup).
3. **Map Your Data**
Under `Setup Inputs`, map the required columns:
* `First Name` (required)
* `Last Name` (required)
* `Email` (required)
All other fields are optional.
If you are adding a custom variable, it must already exist in EmailBison. Follow the steps below to create a custom variable if needed.
If you need to create a custom variable before running the Create or Update Lead enrichment:
1. Click `+ Add column`, select `Enrichments`, and search for `HTTP API` enrichment
2. Select `Configure` and authenticate through one of your connected accounts
If you don't see any accounts, follow the [authentication instructions](/low-code-tools/clay/authenticating-requests).
3. Under `Setup Inputs` → `Method`, select `POST`
4. Under `Setup Inputs` → `Endpoint`, input:
```bash theme={null}
https://subdomain.yourdomain.com/api/custom-variables
```
5. In `Setup Inputs` → `Body`, input:
```json theme={null}
{
"name": "New Name"
}
```
Where `"New Name"` is the value of your new custom variable name.
**Example:**
```json theme={null}
{
"name": "Industry"
}
```
You may also map this value using `/` to insert data from a column.
6. Save the enrichment and run it to see the response
4. **Configure Update Behavior**
Under `Setup Input` → `Select existing lead behaviour`, you have two options:
* `PUT` (Full Replacement) - Replaces the entire lead with only the fields you send. Any fields you don't include will be removed.
* `PATCH` (Partial Update) - Updates only the specific fields you send. All other fields remain unchanged.
Select the option that works best for your use case.
**PUT Example (Full Replacement)**
If you send:
```json theme={null}
{
"first_name": "Alex",
"email": "alex@new.com"
}
```
And the existing lead has:
```json theme={null}
{
"first_name": "Alex",
"email": "alex@example.com",
"phone": "123-4567"
}
```
**Result:** The lead is replaced with only the fields you sent. The `phone` field is **removed** because it wasn't included.
***
**PATCH Example (Partial Update)**
If you send:
```json theme={null}
{
"email": "alex@new.com"
}
```
And the existing lead has:
```json theme={null}
{
"first_name": "Alex",
"email": "alex@example.com",
"phone": "123-4567"
}
```
**Result:** Only the `email` is updated to `alex@new.com`. The `first_name` and `phone` fields remain unchanged.
5. **Save and Run**
After you've filled out all the required fields, save and add the enrichment as a column in your table. Run it to create or update leads in your workspace.
Set this column to auto-run if you need your leads to be added or updated whenever new data flows into your table.
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
The following video will implement the text instructions on a Clay table.
# Find Lead
Source: https://docs.emailbison.com/low-code-tools/clay/enrichments/find-lead
Search for and retrieve lead information from your EmailBison workspace.
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
1. **Add the Enrichment**
* In your Clay table, click `+ Add column`
* Select `Enrichments`
* Search for and select `"Find lead"`
2. **Select Your Workspace**
Choose your desired EmailBison account (workspace) from the dropdown.
If you don't see your workspace, click `+ Add account` and [connect your workspace](/low-code-tools/clay/workspace-setup).
3. **Map Your Search Criteria**
Under `Setup Inputs`, map one of the following required columns:
* `Email`, or
* `Lead ID`
4. **Add Fields**
After mapping, click `Continue` to add fields.
5. **Select Data Columns**
Select your desired data columns that will be added to your table.
6. **Save and Run**
Save the enrichment and run the column.
Set this column to auto-run if data updates elsewhere and you need your leads to be added or updated whenever new data flows in.
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
The following video will implement the text instructions on a Clay table.
# Import Lead(s) to Campaign
Source: https://docs.emailbison.com/low-code-tools/clay/enrichments/import-leads-to-campaign
Add leads to specific EmailBison campaigns directly from your Clay table.
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
1. **Add the Enrichment**
* In your Clay table, click `+ Add column`
* Select `Enrichments`
* Search for and select `"Import lead(s) to campaign"`
2. **Select Your Workspace**
Choose your desired EmailBison account (workspace) from the dropdown.
If you don't see your workspace, click `+ Add account` and [connect your workspace](/low-code-tools/clay/workspace-setup).
3. **Map Required Fields**
Under `Setup Inputs`, map the following required columns:
* `Campaign ID`
* `Lead ID(s)`
If you need to retrieve Campaign IDs, you can either:
Go to an EmailBison campaign. Click `Actions`, `Copy ID for API`.
\-- or --
1. Click `+ Add column`, select `Enrichments`, and search for `HTTP API` enrichment
2. Select `Configure` and authenticate through one of your connected accounts
If you don't see any accounts, follow the [authentication instructions](/low-code-tools/clay/authenticating-requests).
3. Under `Setup Inputs` → `Method`, select `GET`
4. Under `Setup Inputs` → `Endpoint`, input:
```bash theme={null}
https://subdomain.yourdomain.com/api/campaigns
```
5. Save and run the enrichment to see your available campaigns
4. **Select Campaign and Leads**
Select the `Campaign ID` from your available campaigns.
For `Lead ID(s)`, you have several options:
* Use the ID from the [Create or Update Lead](/low-code-tools/clay/enrichments/create-or-update-lead) enrichment response
* Use the ID from the [Find Lead](/low-code-tools/clay/enrichments/find-lead) enrichment response
* Use a [GET request with leads endpoint](/low-code-tools/clay/get-requests)
* Supply a comma-separated list (e.g., `"123,456,789"`) to add multiple leads at once
The Lead ID(s) data type must be changed from `#` to `text`, or you will get a runtime error.
5. **Configure Parallel Sending**
Toggle `parallel sending on` to import leads that are already in another campaign. By default, leads that are "in sequence" in other campaigns will be skipped. This includes leads in draft campaigns. Note that paused campaigns don't count for the parallel sending check, so leads can be added to other campaigns even with the toggle OFF.
6. **Save and Run**
Save the enrichment and run the column to import leads to your campaign.
Set this column to auto-run if you need leads added or updated automatically when new data flows in.
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
The following video will implement the text instructions on a Clay table.
# Remove Domain from Blocklist
Source: https://docs.emailbison.com/low-code-tools/clay/enrichments/remove-domain-from-blocklist
Remove domains from your EmailBison blocklist.
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
1. **Add the Enrichment**
* In your Clay table, click `+ Add column`
* Select `Enrichments`
* Search for and select `"Remove domain from blocklist"`
2. **Select Your Workspace**
Choose your desired EmailBison account (workspace) from the dropdown.
If you don't see your workspace, click `+ Add account` and [connect your workspace](/low-code-tools/clay/workspace-setup).
3. **Map the Required Column**
Under `Column mapping`, map the required column:
* `Domain` (or `Blocklisted Domain ID`)
4. **Save and Run**
Save the enrichment and run the column to remove the domains in the domain column from the blocklist.
Set this column to auto-run if data updates elsewhere and you need your leads to be added or updated whenever new data flows in.
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
The following video will implement the text instructions on a Clay table.
# Remove Email from Blocklist
Source: https://docs.emailbison.com/low-code-tools/clay/enrichments/remove-email-from-blocklist
Remove specific email addresses from your EmailBison blocklist.
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
1. **Add the Enrichment**
* In your Clay table, click `+ Add column`
* Select `Enrichments`
* Search for and select `"Remove email from blocklist"`
2. **Select Your Workspace**
Choose your desired EmailBison account (workspace) from the dropdown.
If you don't see your workspace, click `+ Add account` and [connect your workspace](/low-code-tools/clay/workspace-setup).
3. **Map the Required Column**
Under `Column mapping`, map the required column:
* `Email address` (or `Blocklisted Email ID`)
4. **Save and Run**
Save the enrichment and run the column to remove the emails in the email column from the blocklist.
Set this column to auto-run if data updates elsewhere and you need your leads to be added or updated whenever new data flows in.
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
The following video will implement the text instructions on a Clay table.
# GET Requests (with examples)
Source: https://docs.emailbison.com/low-code-tools/clay/get-requests
This page covers using GET requests for all non-native actions, the majority of use cases can use the [native EmailBison enrichments](/low-code-tools/clay/enrichments).
This page will give step-by-step instructions on making a GET request from Clay to EmailBison.
This example can be altered for different GET endpoints, the overall Clay enrichment will be almost identical.
For an example of a GET request, we will make a request to the [leads endpoint](https://dedi.emailbison.com/api/reference#tag/leads/get/api/leads).
```bash theme={null}
/api/leads
```
And we will pass in the following filters:
```json theme={null}
search : john
filters: tag_ids = [11, 12]
filters: replies = 0
```
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
1. In your Clay table, add a new column. Select `Add enrichment`.
2. Search for and select `HTTP API`.
3. Authenticate through one of the methods listed above (select an account, or pass in an `Authorization` header).
For this example, we will select an account from the dropdown.
4. Under `Setup Inputs` -> `Method`, select `GET` from the dropdown.
5. Under `Setup Inputs` -> `Endpoint`, input the leads endpoint.
```bash theme={null}
https://subdomain.yourdomain.com/api/leads
```
6. Under `Setup Inputs` -> `Query Parameters`, select `Add a new Key and Value pair` for each of the following steps.
7. Input `search` as the Key, and `john` as the Value.
8. Input `filters[replies][value]` as the Key, and `0` as the Value.
9. Input `filters[replies][criteria]` as the Key, and `=` as the Value.
10. Since Clay doesn't support duplicate keys, we need to pass an array with indexes, i.e. `tag_ids[0]` instead of `tag_ids[]`
11. Input `filters[tag_ids][0]` as the Key, and `11` as the Value.
12. Input `filters[tag_ids][1]` as the Key, and `12` as the Value.
13. Save the enrichment.
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
The following video will implement the text instructions on a Clay table.
***
When this column runs, it will make a GET request to EmailBison fetching leads with these criteria. To use dynamic query parameters, use Clay's built-in `/` feature to pick data from previous columns.
# Overview
Source: https://docs.emailbison.com/low-code-tools/clay/overview
## Official EmailBison Integration (Recommended)
EmailBison enrichments are available natively in Clay.
To get started:
1. [Connect your workspace](/low-code-tools/clay/workspace-setup)
2. Browse [available enrichments](/low-code-tools/clay/enrichments)
## HTTP API Method (Alternative)
The integration between EmailBison and Clay can also be done through the `HTTP API (with headers)` enrichment.
If you haven't visited [Low-Code Tools - Introduction](/low-code-tools/introduction) yet, it provides a high-level overview of what to expect when translating API calls into the equivalent feature for low-code tools.
The pages in this section will show step-by-step instructions, as well as accompanying videos.
Although the steps are for specific requests, they can be easily altered to any other EmailBison endpoint.
Every `HTTP API` enrichment will need to be authenticated, so make sure you follow [Clay - Authenticating](/low-code-tools/clay/authenticating-requests) first.
# POST Requests (with examples)
Source: https://docs.emailbison.com/low-code-tools/clay/post-requests
This page covers using POST requests for all non-native actions, the majority of use cases can use the [native EmailBison enrichments](/low-code-tools/clay/enrichments).
This page will give step-by-step instructions on making POST requests from Clay to EmailBison.
These instructions can be slightly altered for different POST, PUT, and PATCH endpoints, the overall Clay enrichment will be the same.
This page will provide the instructions to [add leads to EmailBison](/leads/creating-a-lead), and then chain an API call to [add the leads to a campaign](/campaigns/adding-leads-to-a-campaign).
## 1. Adding a lead to EmailBison
For this example, we have a Clay table containing leads with the following columns.
```json theme={null}
Email
First Name
Last Name
Company
Title
Notes
AI Enriched Paragraph
Linkedin URL
```
We will start by creating a column that will add each lead to EmailBison.
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
1. In your Clay table, add a new column. Select `Add enrichment`.
2. Search for and select `HTTP API`.
3. Authenticate through one of the methods listed above (select an account, or pass in an `Authorization` header).
For this example, we will select an account from the dropdown.
4. Under `Setup Inputs` -> `Method`, select `POST` from the dropdown.
5. Under `Setup Inputs` -> `Endpoint`, input the leads endpoint.
```bash theme={null}
https://subdomain.yourdomain.com/api/leads
```
6. For the body of the request in `Setup Inputs` -> `Body`, refernce the `API Reference` to view the parameters this request takes.
7. For example, for the `first_name` parameter, we will input `/` and find the `First Name` column in our Clay table.
8. Repeat this step for all the columns in your Clay table. For any columns in the table that are not specifically named in the EmailBison request, we will use the `custom_variables` array. An example would be `AI Enriched Paragraph` or `Linkedin URL`
9. The final request will look like the following image.
10. Save the enrichment
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
The following video will implement the text instructions on a Clay table.
## 2. Attaching a lead to an EmailBison campaign
These instructions will follow the previous instructions.
We will also assume we have a Clay column that decides which campaign each lead will go to.
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
1. In your Clay table, add a new column. Select `Add enrichment`.
2. Search for and select `HTTP API`.
3. Authenticate through one of the methods listed above (select an account, or pass in an `Authorization` header).
For this example, we will select an account from the dropdown.
4. Under `Setup Inputs` -> `Method`, select `POST` from the dropdown.
5. Under `Setup Inputs` -> `Endpoint`, input the attach leads to campaign endpoint.
```bash theme={null}
https://subdomain.yourdomain.com/api/campaigns/{campaign_id}/leads/attach-leads
```
6. Replace `{campaign_id}` with the ID of the EmailBison campaign you want these leads to be attached to. Alternatively, use the Clay `/` feature to use the the Clay column that contains the campaign ID.
7. For the body of the request, refernce the `API Reference` to view the parameters this request takes.
8. Under `Setup Inputs` -> `Body`, input the JSON curly braces (`{}`), a key named `lead_ids`, and then square brackets (`[]`) to denote an array.
9. For the value of the `lead_ids` array, input `/`, find the `HTTP API` enrichment that ran before this one, click on it, click on `data`, and then click on `id`. This is the ID EmailBison will use to identify this lead, and returns to you when you create a lead.
10. Save the enrichment.
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
The following video will implement the text instructions on a Clay table.
***
After implementing these steps, every row (lead) in your Clay table will be added to EmailBison, and then attached to a campaign you choose after the enrichments run.
# Workspace Setup
Source: https://docs.emailbison.com/low-code-tools/clay/workspace-setup
Before using the official EmailBison integration in Clay, you'll need to connect your EmailBison workspace(s).
In order to access each workspace's data (to push or pull data), you will need to create an `api-user` key for each workspace and connect them one by one in Clay.
There are two ways to connect your workspace:
## Method 1: From Clay Settings
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
1. **Access Clay Settings**
Go to Clay settings and navigate to the `Connections` tab.
2. **Add EmailBison Connection**
Click `+ Add connection` and search for `EmailBison`.
3. **Enter Workspace Details**
Input the following:
* **Connection name** - Your workspace name
* **Workspace domain (Instance URL)** - Your workspace domain (this will always be your instance URL)
* **API Key** - Your user-api key (see [API Key](/get-started/authentication))
4. **Save**
Click `Save`. You can now select this workspace from the `Account` dropdown for any EmailBison enrichment.
5. **Adding Multiple Workspaces**
Repeat these steps for each workspace you want to connect to Clay. Each workspace requires its own `api-user` key.
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
The following video will implement the text instructions on a Clay table.
## Method 2: From Within an Enrichment
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
1. **Access EmailBison Enrichments**
Click on `Actions`, or click `+ Add column` then `Add enrichment`.
Search `emailbison` and select any of the enrichments.
2. **Add Your Workspace Account**
Under `Account`, click `+ Add account`.
3. **Enter Workspace Details**
Input the following:
* **Connection name** - Your workspace name
* **Workspace domain (Instance URL)** - Your workspace domain (this will always be your instance URL)
* **API Key** - Your user-api key (see [API Key](/get-started/authentication))
4. **Save**
Click `Save`. You can now select this workspace from the `Account` dropdown for any EmailBison enrichment.
5. **Adding Multiple Workspaces**
Repeat these steps for each workspace you want to connect to Clay. Each workspace requires its own `api-user` key.
There are text and video versions of this section.
Click the tab icons above this tip to switch between them.
The following video will implement the text instructions on a Clay table.
***
Once you've connected your workspace(s), browse the [available enrichments](/low-code-tools/clay/enrichments) to start integrating EmailBison with your Clay tables.
# Introduction
Source: https://docs.emailbison.com/low-code-tools/introduction
Automations can be set-up using low-code / no-code tools. Tools such as [n8n](https://n8n.io), [Clay](https://clay.com), [Zapier](https://zapier.com), [Make](https://make.com).
Clay users have access to an official EmailBison integration with pre-built enrichments. See [Clay - Overview](/low-code-tools/clay/overview) to get started.
The interaction between these tools and EmailBison will be done through the following.
1. Listening to the [EmailBison Webhooks](/webhooks/overview)
2. Making API requests
## Translating API calls
There are general guidelines on translating the API calls found in these docs and in the API reference. Please consult the documentation for your specific tool to supplement this.
Hover over names to see other common names found in these tools.
* Authorization -- A header with your request with a `Authorization` key and a `Bearer {api_key}` value. Automation tools usually have a method of saving these tokens to be used for multiple automations, instead of having to pass in a header in your automation requests.
* HTTP Method -- One of `GET`, `DELETE`, `POST`, `PUT`, `PATCH`. This needs to match the HTTP method found in these docs, or the API Reference.
* Endpoint -- This is the path to the endpoint you wish to use in your automation. *Example: `https://send.greenmarketing.com/api/leads`*
* Query Parameters -- Used for GET requests, like this [getting replies request](master-inbox/fetching-replies). The parameters are usually sent one by one in these tools with an entry for the name of the parameter, and the value. [More info](get-started/quickstart/notes-and-terminology#query-parameters).
* Body -- This will be 1:1 with the examples provided in this documentation and the API reference.
# Attaching Leads to Untracked Replies
Source: https://docs.emailbison.com/master-inbox/attaching-leads-to-untracked-replies
Untracked replies in the master inbox will show up with a button to `Attach Contact`.
This action can be done on a larger scale using the API.
## Getting all scheduled emails for a lead
Send a `GET` request to the following endpoint
```bash theme={null}
/api/scheduled-emails/{lead_id_or_email}
```
## Attaching scheduled emails to a reply
Once you have the scheduled email IDs you can attach them to replies with their ID.
Send a `POST` request to the following endpoint
```bash theme={null}
api/replies/{reply_id}/attach-email-to-reply
```
The following are the parameters for the request.
The ID of the scheduled email you to attach to the reply.
# Getting Replies and Campaign Emails For a Lead
Source: https://docs.emailbison.com/master-inbox/fetching-replies
## Getting Replies for a Lead
Send a `GET` request to
```bash theme={null}
/api/leads/{lead_id}/replies
```
The following are the parameters for the request.
The ID or email of the lead.
Search term for filtering replies.
Filter by status. One of interested, automated\_reply, not\_automated\_reply.
Filter by folder. One of inbox, sent, spam, bounced, all.
Filter by read status.
The ID of the campaign.
The ID of the sender email address.
Array of tag IDs to filter by.
## Getting Campaign Emails for a Lead
Send a `GET` request to
```bash theme={null}
/api/leads/{lead_id_or_email}/sent-emails
```
The following are the parameters for the request.
The ID or email of the lead.
# Overview
Source: https://docs.emailbison.com/master-inbox/overview
The Master Inbox is a unified inbox view into all your sender email accounts connected in a workspace.
## Filtering
The Master Inbox can be filtered to show replies from specific:
* Campaigns
* Reply statuses
* Sender Emails
* Lead tags
## Emails Synced
EmailBison will sync every email recieved by your Sender Emails by default, this could include warmup emails from other tools.
To ignore these emails, you can turn on the 'Smart filter warmup emails from other providers' in `Settings` -> `Master Inbox`. If some warmup emails from other tools are still being synced, you can add ignore phrases in `Settings` -> `Master Inbox` -> `New Ignore Phrase`.
# Responding to Messages
Source: https://docs.emailbison.com/master-inbox/responding-to-messages
Send a `POST` request to the following endpoint.
```bash theme={null}
/api/replies/{reply_id}/reply
```
The following are the parameters for the request.
The ID of the parent reply.
The contents of the reply
The ID of the sender email
Array of people to send this email to.
The name field in the object can be nulled (left empty).
Example:
`[ { "name": "John Doe", "email_address": "john@example.com" } ]`
Whether to inject the body of the previous email into this email. If nothing sent, false is assumed
Type of the email (html or text)
An array of people to send a copy of this email to (Carbon Copy).
The name field in the object can be nulled (left empty).
Example:
`[ { "name": "John Doe", "email_address": "john@example.com" } ]`
An array of people to send a blind copy of this email to (Blind Carbon Copy).
The name field in the object can be nulled (left empty).
Example:
`[ { "name": "John Doe", "email_address": "john@example.com" } ]`
# Attaching Tags
Source: https://docs.emailbison.com/tags/attaching-tags
## Attaching Tags
Tags can be attached to any *taggable* -- `leads`, `sender emails`, and `campaigns`.
Send a `POST` request to one of the [following endpoints](https://dedi.emailbison.com/api/reference#tag/custom-tags).
```bash theme={null}
/api/tags/attach-to-sender-emails
```
```bash theme={null}
/api/tags/attach-to-leads
```
```bash theme={null}
/api/tags/attach-to-campaigns
```
The fields for these endpoints are:
An array of tag IDs to attach
An array of taggables to attach the tags to.
One of `sender_email_ids`, `lead_ids`, `campaign_ids`.
An example of a request to attach tags with IDs 1 and 2 to sender emails with IDs 3 and 4:
```bash curl {6,7} theme={null}
curl 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]
}'
```
```JavaScript JavaScript {8,9} theme={null}
fetch('https://dedi.emailbison.com/api/tags/attach-to-sender-emails', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: 'Bearer YOUR_SECRET_TOKEN'
},
body: JSON.stringify({
tag_ids: [1, 2],
sender_email_ids: [3, 4]
})
})
```
```Python Python {7,8} theme={null}
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_SECRET_TOKEN',
}
json_data = {
'tag_ids': [1, 2],
'sender_email_ids': [3, 4]
}
response = requests.post('https://dedi.emailbison.com/api/tags/attach-to-sender-emails', headers=headers, json=json_data)
```
1. Navigate to the `Campaigns`, `Email Accounts`, or `Contacts` tab.
2. Filter and select taggables by clicking on the checkboxes on the left hand side.
3. After selecting, a `Add tags` button will appear.
4. Select tags from the dropdown, and click `Attach tags`.
# Creating Tags
Source: https://docs.emailbison.com/tags/creating-tags
Tags are a way for you to seperate different leads/sender emails/campaigns into their own categories.
Send a `POST` request to the [following endpoint](https://dedi.emailbison.com/api/reference#tag/custom-tags/post/api/tags).
```bash theme={null}
/api/tags
```
There are 2 fields you can provide, `name` and `default`.
A name for the tag.
Whether this is a default tag.
An example of a request in curl:
```bash theme={null}
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
}'
```
1. Navigate to `Settings` -> `Custom Tags`
2. Click on `Create custom tag`, provide a name for your tag, click on `Create custom tag`.
# Overview
Source: https://docs.emailbison.com/tags/overview
Tags can be attached to any taggable record, and help organize your workspace as well as trigger workflows as they [emit webhooks](/webhooks/overview).
Tags are unique per workspace, and tags created in a workspace will not be created in other workspaces.
## Taggables
Taggables are the records that can be tagged. They are [leads](/leads/overview), [campaigns](/campaigns/overview), and [sender emails](/email-accounts/overview).
Any tag can be attached to any taggable.
## Default Tags
Every workspace will have the same following tags created by default.
```json theme={null}
Interested
Meeting Booked
Google
Outlook
Zoho
Custom Mail Server
Proofpoint
Mimecast
Barracuda
Automated Reply
```
If you wish to create more tags automatically when a workspace is created, the [creating template workspaces walktrough](/walkthroughs/creating-template-workspaces) contains instructions on how to do so.
# Removing Tags
Source: https://docs.emailbison.com/tags/removing-tags
## Removing Tags
Send a `DELETE` request to one of the [following endpoints](https://dedi.emailbison.com/api/reference#tag/custom-tags).
```bash theme={null}
/api/tags/attach-to-sender-emails
```
```bash theme={null}
/api/tags/attach-to-leads
```
```bash theme={null}
/api/tags/attach-to-campaigns
```
The fields for these endpoints are:
An array of tag IDs to remove.
An array of taggables to remove the tags from.
One of `sender_email_ids`, `lead_ids`, `campaign_ids`.
An example of a request to remove tags with IDs 1 and 2 from sender emails with IDs 3 and 4:
```bash curl {6,7} theme={null}
curl https://dedi.emailbison.com/api/tags/attach-to-sender-emails \
--request DELETE \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"tag_ids": [1, 2],
"sender_email_ids": [3, 4]
}'
```
```JavaScript JavaScript {8,9} theme={null}
fetch('https://dedi.emailbison.com/api/tags/attach-to-sender-emails', {
method: 'DELETE',
headers: {
'Content-Type': 'application/json',
Authorization: 'Bearer YOUR_SECRET_TOKEN'
},
body: JSON.stringify({
tag_ids: [1, 2],
sender_email_ids: [3, 4]
})
})
```
```Python Python {7,8} theme={null}
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_SECRET_TOKEN',
}
json_data = {
'tag_ids': [1, 2],
'sender_email_ids': [3, 4]
}
response = requests.delete('https://dedi.emailbison.com/api/tags/attach-to-sender-emails', headers=headers, json=json_data)
```
1. Navigate to the `Campaigns`, `Email Accounts`, or `Contacts` tab.
2. Filter and select taggables by clicking on the checkboxes on the left hand side.
3. After selecting, a `Remove tags` button will appear.
4. Select tags from the dropdown, and click `Remove tags`.
# Creating Template Workspaces
Source: https://docs.emailbison.com/walkthroughs/creating-template-workspaces
Click the tabs at the top of the page for the walkthrough on different tools.
This walkthrough will go over creating a workspace with the same base set-up each time.
This is useful when you have common factors you re-create manually in every new workspace you create.
For this walkthrough, the following manual steps are assumed to be done each time a workspace is created.
* Three users are invited (and they have to manually accept the invitations).
* Four [custom tags](/tags/creating-tags) are created.
* An [API token](/get-started/authentication#api-keys) is created.
* A [webhook](/webhooks/overview) is created, with the same events listened to.
To automate all these steps, including accepting the invitations, start by making a new automation in your preferred tool. This automation will need a `super-admin` token for the first 2 requests, it is then able to switch to using the `api-user` token it created itself.
Click the tabs at the top of the page for the walkthrough on different tools.
This tab will follow a netural style, to help you translate this walkthrough into your preffered tool.
1. The automation will make a `POST` request to create a workspace at this endpoint.
```bash theme={null}
/api/workspaces/v1.1
```
2. The automation will create an API token for this workspace by sending a `POST` request to this endpoint. The automation will use the `team_id` returned in the first request.
```bash theme={null}
/api/workspaces/v1.1/{team_id}/api-tokens
```
3. From this point, the `super-admin` key is no longer required, the automation will switch to using the `api-user` key just created and returned in the last response.
4. For each of the 3 users, the automation will invite them by sending a `POST` request to this endpoint.
```bash theme={null}
/api/workspaces/v1.1/invite-members
```
5. The automation will then chain a `POST` request to this endpoint, using the `team_invitation_id` returned from the previous request.
```bash theme={null}
/api/workspaces/v1.1/accept/{team_invitation_id}
```
6. The automation will create the four tags on the workspace by sending a `POST` request to this endpoint.
```bash theme={null}
/api/tags
```
7. The automation will create the webhook on the workspace by sending a `POST` request to this endpoint.
```bash theme={null}
/api/webhook-url
```
The automation will have created the workspace with the desired set-up at this point.
Click the tabs at the top of the page for the walkthrough on different tools.
This tab will provide the instructions on achieving this walkthrough using n8n.
# Send Slack Message on Campaign Reply
Source: https://docs.emailbison.com/walkthroughs/send-slack-message-on-reply
Click the tabs at the top of the page for the walkthrough on different tools.
This walkthrough will go over sending a Slack message everytime you get a campaign reply on a workspace.
Although this workspace is specific to campaign replies, it can be easily altered for different events such as when an untracked reply is received, when a sender email disconnects etc. by listening to different [webhook events](/webhooks/when-are-webhooks-triggered).
Click the tabs at the top of the page for the walkthrough on different tools.
This tab will follow a netural style, to help you translate this walkthrough into your preffered tool.
Click the tabs at the top of the page for the walkthrough on different tools.
This tab will provide the instructions on achieving this walkthrough using n8n.
Navigate to `https://n8n.io`.
In a workspace, click the `+` to add a new node.
Search for Webhook and click on it.
Set the `HTTP Method` in the webhook to `POST`.
Copy the Test URL to put into EmailBison later.
Add a new node for slack by clicking on the `+` again.
Search for "Slack", click on it, then search for "Send a message", click on it.
On the `Credential to connect with` input field, click `Create new credential`, make sure it is on `OAuth2`, click `Connect my account`.
Proceed with the Slack login, close the pop-up after it says `Account Connected`.
Fill out the input fields with the desired channel you want the updates sent to.
In EmailBison, navigate to `Settings` -> `Webhooks` -> `New Webhook URL`.
Give a name for your webhook and paste the n8n Test URL you copied earlier into the input field.
Toggle on `Contact Replied` and click `Subscribe to webhooks`.
Navigate back to your n8n workbook. Double-click on the Webhook node, click `Listen for test event`.
Navigate to the webhook you created on EmailBison, click on `Send test webhook`, select `Contact replied` as the webhook event, click `Send test event`.
To extract the data you want from the webhook, Double-click on your Slack node in your n8n workbook.
On the `Message Text` field, switch it from `fixed` to `expression`.
Drag and Drop the desired fields from the `input` tab on the left-hand side.
Click on `Test step` on the top of the page, you should receive a Slack message with the details you chose.
In your n8n workbook, double click the Webhook node.
Under `Webhook URLs`, switch the button from `Test URL` to `Production URL`, copy this URL.
Navigate to EmailBison -> `Settings` -> Webhooks. Click edit on the Webhook you just created, replace the Webhook URL with the production URL you just copied.
You should now receive a Slack message on every campaign reply in that workspace.
# Events, Deliveries, and Attempts
Source: https://docs.emailbison.com/webhooks/events-deliveries-and-attempts
#### Events
Events are important things that happen in a workspace. These are usually tied to actions taken. For example, an email being sent, a lead replying, etc.
When you add a webhook listener and give us a URL to send to, we pass over raw event data.
The event payload matches the webhook payload exactly.
You can see events for the past 10 days with all of their payloads, webhook deliveries, and webhook attempts. From the UI, navigate to Settings -> Events. Or, you could use the */api/events* endpoint.
#### Webhook Deliveries
A webhook delivery is a single delivery to a single webhook listener. For example, say that you have 3 total URLs you want to receive a *lead replied* webhook to. This would translate to 3 specific webhook deliveries from our side. An 'Event' can have multiple webhook deliveries tied to it, with each delivery being tied to a webhook listener URL that you’ve defined. Webhook deliveries can be managed per event through: Settings -> Events -> Webhook Deliveries, or via the API.
#### Webhook Attempts
A webhook attempt is our attempt to send the event to your registered webhook URL. Therefore, a webhook delivery can have multiple “attempts.”
Ideally, if your webhook listener URL responds with a 200 code, you will only see 1 attempt per webhook delivery.
But in cases where your listener might be timing out, or returning an unsuccessful (eg non 200 response code), there will be multiple attempts made. If an attempt receives no reponse in 15 seconds, it will time out.
If you ever have downtime on your listeners, you can play back these attempts by “resending” the webhook attempt to your URL.
This is possible via the UI in settings -> events -> webhook deliveries -> manage -> resend webhook attempt, or via the API.
We strongly recommend playing webhook events via the API by filtering for events given a start and end date, and then calling the *resend* endpoint on the webhook\_attempt\_id.
# Overview
Source: https://docs.emailbison.com/webhooks/overview
A webhook is an HTTP request that is automatically sent by a source of data when an event is triggered. In this case, the source of data is your EmailBison instance.
EmailBison provides you with many events to trigger a webhook request. To view all the events available, navigate to `Settings` -> `Webhooks` -> `New Webhook URL`.
The different events contain sample payloads under the toggle for you to preview the data sent.
## Sending Test Events
To test your automations, you can send a test webhook natively in app by navigating to `Settings` -> `Webhooks` -> `New Webhook URL` or click `Edit` on a webhook, and then click on `Send test webhook`.
You can also send a test event through the API by sending a `POST` request at the [following endpoint](https://dedi.emailbison.com/api/reference#tag/webhook-events/post/api/webhook-events/test-event).
```bash theme={null}
/api/webhook-events/test-event
```
# When are Webhooks Triggered
Source: https://docs.emailbison.com/webhooks/when-are-webhooks-triggered
On this page you will find all the webhooks available in EmailBison, and their trigger conditions.
#### Email Sent
Triggered only when a campaign email is sent.
#### Manual Email Sent
Triggered only when a manual email sent. This includes replying and composing new emails -- both from the master inbox or the API.
#### Contact First Emailed
Triggered only when a contact received the first campaign email on this workspace.
#### Contact Replied
Triggered every time a lead that was emailed from a campaign replies.
Will **not** trigger if the campaign the lead is in has the setting `Include auto replies in stats` is toggled off and it is an automated reply.
#### Contact Interested
Will trigger if a reply gets marked as interested through the master inbox, the API, or automatically if `Auto AI categorization` is toggled on in the general master inbox settings.
#### Contact Unsubscribed
Triggered when a lead is unsubscribed from campaigns.
#### Untracked Reply Received
Triggered when a new email or a reply is received, and it is not associated with a scheduled email that was sent from a campaign.
#### Email Opened
Triggered when an email is opened, this needs the campaign to have `track opens` toggled on.
#### Email Bounced
Triggered when a campaign email bounces.
#### Email Account Added
Triggered every time a sender email is connected for the first time.
#### Email Account Removed
Triggered every time a sender email is removed (deleted).
#### Email Account Disconnected
Triggered every time a sender email is disconnected.
This will also trigger if it is a Microsoft account and the refresh [token has expired.](https://help.bisonsphere.com/en/articles/19-microsoft-accounts-90-day-expiry)
#### Email Account Reconnected
Triggered every time a sender email is reconnected, after it has been disconnected.
#### Tag Attached
Triggered every time a custom tag is attached to a taggable (lead, sender email, or campaign).
This will send one webhook per tag attached, per taggable.
#### Tag Removed
Triggered every time a custom tag is removed from a taggable (lead, sender email, or campaign).
This will send one webhook per tag removed, per taggable.
#### Warmup Disabled Causing Bounces
Triggered when warmup for a sender email was disabled for causing too many bounces
#### Warmup Disabled Receiving Bounces
Triggered when warmup for a sender email was disabled for receiving too many bounces
#### Blacklisted Email Added
A Blacklisted Email Was Added \
Will **not** trigger via the API *if* you set the *skip\_webhooks* parameter to true.
#### Blacklisted Email Removed
Blacklisted Email Removed \
Will **not** trigger via the API *if* you set the *skip\_webhooks* parameter to true.
#### Blacklisted Domain Added
Blacklisted Domain Added \
Will **not** trigger via the API *if* you set the *skip\_webhooks* parameter to true.
#### Blacklisted Domain Removed
A Blacklisted Domain Was Removed \
Will **not** trigger via the API *if* you set the *skip\_webhooks* parameter to true.
#### Email Send Failed
A scheduled campaign email failed to send
#### Manual Email Send Failed
A manual email failed to send
# Creating API Keys
Source: https://docs.emailbison.com/workspaces/creating-api-keys
**This workflow requires a `super-admin` key.**
For a refresher on the difference between the key types, you can visit [Authentication](/get-started/authentication).
You do not need to switch workspaces using the API or the UI for this workflow.
`api-user` keys can be generated for workspaces using the API.
### Creating a Key
Send a `POST` request to the following endpoint.
```bash theme={null}
/api/workspaces/v1.1/{workspace_id}/api-tokens
```
The ID of the workspace you want to generate a key for.
Workspace IDs can be aquired by sending a `GET` request to `api/v1.1/workspaces`.
You must include a `name` field in a JSON body, this field is the name of the API key you are creating.
An example of a request creating an API key named "**New token**" for the workspace with ID **54**:
```bash curl theme={null}
curl 'https://dedi.emailbison.com/api/workspaces/v1.1/54/api-tokens' \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"name": "New token"
}'
```
```JavaScript JavaScript theme={null}
fetch('https://dedi.emailbison.com/api/workspaces/v1.1/54/api-tokens', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: 'Bearer YOUR_SECRET_TOKEN'
},
body: JSON.stringify({
name: 'New token'
})
})
```
```Python Python theme={null}
import requests
url = "https://dedi.emailbison.com/api/workspaces/v1.1/54/api-tokens"
payload = { "name": "New token" }
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_SECRET_TOKEN"
}
response = requests.post(url, json=payload, headers=headers)
```
1. Navigate to `Settings` -> `Developer API`.
2. Click the `New API Token` button near the top-right of the page.
3. Provide a token name and token type.
4. Click `Generate Token`.
# Creating Users
Source: https://docs.emailbison.com/workspaces/creating-users
If a user (associated with an email account) has not registered yet for any of your workspaces on your EmailBison instance, you can programmatically register that email account using the API.
If they have already registered, and you want to give them access to other workspaces using the API, visit the [Inviting and Accepting Members](/workspaces/inviting-and-accepting-members) page.
### Creating a User
Send a `POST` request to the [following endpoint](https://dedi.emailbison.com/api/reference#tag/workspaces-v11/post/api/workspaces/v1.1/users).
```bash theme={null}
/api/workspaces/v1.1/users
```
This request takes a [JSON body](/get-started/quickstart/notes-and-terminology#body-parameters) with the following 4 fields.
A name for the user.
A password for the user.
The email address of the user.
A role for the user. One of `admin`, `editor`, `client`.
An example of a request creating a user:
```bash curl theme={null}
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": "securepasswordlol",
"email": "example@example.com",
"role": "admin"
}'
```
```JavaScript JavaScript theme={null}
fetch('https://dedi.emailbison.com/api/workspaces/v1.1/users', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: 'Bearer YOUR_SECRET_TOKEN'
},
body: JSON.stringify({
name: 'John Doe',
password: 'securepasswordlol',
email: 'example@example.com',
role: 'admin'
})
})
```
```Python Python theme={null}
import requests
url = "https://dedi.emailbison.com/api/workspaces/v1.1/users"
payload = {
"name": "John Doe",
"password": "securepasswordlol",
"email": "example@example.com",
"role": "admin"
}
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_SECRET_TOKEN"
}
response = requests.post(url, json=payload, headers=headers)
```
# Creating Workspaces
Source: https://docs.emailbison.com/workspaces/creating-workspaces
**This workflow requires a `super-admin` key.**
For a refresher on the difference between the key types, you can visit [Authentication](/get-started/authentication).
Workspaces can be created using the API.
### Creating a Workspace
Send a `POST` request to `/api/workspaces/v1.1`.
You must include a `name` field in a JSON body, this field is the name of the workspace you are creating.
An example of a request to create a new workspace with the name **new name**:
```bash curl theme={null}
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 name"
}'
```
```JavaScript JavaScript theme={null}
fetch('https://dedi.emailbison.com/api/workspaces/v1.1', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: 'Bearer YOUR_SECRET_TOKEN'
},
body: JSON.stringify({
name: 'New name'
})
})
```
```Python Python theme={null}
import requests
url = "https://dedi.emailbison.com/api/workspaces/v1.1"
payload = { "name": "New name" }
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_SECRET_TOKEN"
}
response = requests.post(url, json=payload, headers=headers)
```
# Inviting and Accepting Members
Source: https://docs.emailbison.com/workspaces/inviting-and-accepting-members
This workflow requires that the user has already registered on your EmailBison instance. If not, visit the [Creating Users](/workspaces/creating-users) page to add them to your instance using the API.
Existing users can be invited to any workspace using the API. Furthermore, their invitations can be programmatically accepted using the API.
### Inviting Members
If you are also going to be [accepting invitations](/workspaces/inviting-and-accepting-members#accepting-invitations), you will use the ID given in the response of this API call.
Send a `POST` request to `/api/workspaces/v1.1/invite-member`.
This request takes a JSON body with the following 2 required fields:
The email of the registered user.
A role for the user. One of `admin`, `editor`, `client`.
```bash curl theme={null}
curl 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": "example@example.com",
"role": "admin"
}'
```
```JavaScript JavaScript theme={null}
fetch('https://dedi.emailbison.com/api/workspaces/v1.1/invite-members', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: 'Bearer YOUR_SECRET_TOKEN'
},
body: JSON.stringify({
email: 'example@example.com',
role: 'admin'
})
})
```
```Python Python theme={null}
import requests
url = "https://dedi.emailbison.com/api/workspaces/v1.1/invite-members"
payload = {
"email": "example@example.com",
"role": "admin"
}
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_SECRET_TOKEN"
}
response = requests.post(url, json=payload, headers=headers)
```
### Accepting Invitations
You can use the API to accept invitations to workspaces on behalf of users.
Send a `POST` request to `/api/workspaces/v1.1/accept/{team_invitation_id}` where `{team_invitation_id}` is the ID received back when [inviting members](/workspaces/inviting-and-accepting-members#inviting-members).
This request does not take a body.
# Overview
Source: https://docs.emailbison.com/workspaces/overview
Workspaces separate your workflows into an isolated environment.
It is generally recommended to have each client on their own workspace.
## Workspace Scope
Every record in EmailBison is unique per workspace, and you can have the same record in multiple workspaces.
For example, you can have the same [leads](/leads/overview), [tags](/tags/overview), and [custom variables](/leads/overview#custom-variables) in multiple workspaces, and they are all unique with their own individual ID.
The only exception to this is [sender emails](/email-accounts/overview), which can only exist in one workspace at a time.
## API Keys
API requests to EmailBison are always scoped to one workspace, for both [key types](/get-started/authentication). This allows you to have separate automations for each workspace, based on the key you use.