Skip to main content
POST
Attaches every mailbox on your account carrying the given tags to a campaign, resolving the tags server-side. Use this instead of paging through Get All Email Accounts and filtering on the embedded tags array yourself.

Overview

If you organise senders by tag - per client, per domain pool, per reputation tier - this attaches a whole group in one request. Without it you would have to:
  1. Page through GET /email-accounts/ at 100 mailboxes per page.
  2. Filter client-side on each account’s embedded tags array.
  3. POST the resulting IDs to Add Email Accounts.
Use Get All Tags to look up the tag IDs to pass here.
A campaign can hold at most 2,500 mailboxes. If the tags resolve to more than the remaining headroom, the extras are not attached and the response message says how many were left out; if the campaign is already full the request returns 400. (The explicit-ID endpoint accepts a max_limit flag to raise this to 5,000. This endpoint does not - it always uses the 2,500 default.)
This endpoint adds mailboxes only. To detach them, use Remove Email Accounts. It is additive to Add Email Accounts, which is unchanged - keep using that one when you already have mailbox IDs.

Path Parameters

number
required
The campaign ID

Query Parameters

string
required
Your SmartLead API key

Request Body

array
required
Tag IDs to expand. Every mailbox on your account carrying any of these tags is attached.Between 1 and 5 tags per call. Only tags you own are accepted - passing a tag ID belonging to another account returns 400. A tag you own that has no mailboxes is not an error: it returns 200 with added_count: 0.Example: [485775]
boolean
default:"false"
When true, tagged mailboxes that are not fully connected (is_smtp_success and is_imap_success both true) are skipped instead of attached. The number skipped is returned as tag_resolution.skipped_disconnected_count.The default is false so that attaching by tag behaves exactly like posting the same mailbox IDs to Add Email Accounts, which does not filter on connection health either.
boolean
When true, enables warmup auto-adjust on the mailboxes that were attached.

Response Fields

number
How many mailboxes this call newly attached.
number
How many of the resolved mailboxes were already on the campaign and so were left alone.
object
What the tags expanded to.

Response Codes

Success
Request successful. Also returned when the tags matched no mailboxes - check added_count and message.
Bad Request
A tag_ids entry does not belong to your account, tag_ids is missing, empty or longer than 5, or the campaign is already at its mailbox cap.
Unauthorized
Invalid or missing API key.
Not Found
The campaign does not exist or you don’t have access to it.
Internal Server Error
Server error occurred. Please try again or contact support if the issue persists.

Best Practices

Pair with only_connected: by default a disconnected mailbox carrying the tag is still attached, matching the explicit-ID endpoint. On a large tag, only_connected: true keeps dead senders out of the rotation and tells you how many were left behind.
Tags are resolved at call time: adding a mailbox to the tag later does not backfill campaigns you already created. Re-issue the call to pick it up.
Re-running is safe: mailboxes already on the campaign are counted in already_associated_count and not duplicated.