legacy.add_segment

Description

WARNING: This method cannot be combined with any other method call within the same POST command.

When transferring a list of subscribers using the legacy.bulk_sync API, it is often necessary to create a static segment for the subscriber list. Adding a static segment and using the "group_id" returned allows you to post a list of subscribers that will appear separately within the system.

This method also allows you to fill a static segment with a list of contacts using email addresses, provided those email addresses match subscribers already in your subscriber list. This method is also useful to fill a static segment using a list of Mapp contact IDs. You may fill an existing segment by providing a single (or list of) "group_id", and/or fill a new segment by providing a "groupname". The two methods may be combined to create a static segment and fill existing segments within the same API call.

Arguments

Field	Description	Field Type	Required	Example
groupname	The name of the static segment that you wish to create. The name of the new segment must not already exist for this account. Limit: 150 characters.	String	Conditional; this element is required only if the <groups> element is not included in the POST message.	eTail East 2010 Opt-ins
hidden	A boolean value that controls whether the static segment is hidden from a standard survey. 0 -(the default value) make this static segment available for standard surveys. 1 – hide this segment from a standard survey.	Boolean	No	0
category_id	The category ID number that you want to associate the static segment with. Use the method legacy.retrieve_segment to obtain a list of categories and their ID numbers that exist for your account.	Number	No	34985
groups	A comma-delimited list of static segment IDs that you want to add your list of contacts to. If you provide this element, then you must also provide the list of contacts contained within the <contacts> element.	String	Conditional; this element is required only if the <groupname> element is not included in the POST message.;	2678,2679,2790
contacts	A comma-delimited list of email addresses or Mapp Contact IDs that you want to add to the static segments specified either in the <groupname> element or the <groups> element.	String	Conditional; this element is required only if the <groups> element is included in the POST message.	jsmith@​example.com, jane.doe@​example.com or 12345,56789

Response

Field	Description	Example
message	Indicates whether the action was successful or not. 1 – the creation of the new static segment, or the addition of the contacts to the static segment(s) was successful. 2 – the requested action was unsuccessful for the reason specified in the <reason> element	1
group_id	The group_id of the newly created static segment.	39649
reason	Human-readable explanation for the reason of the failure.	not all variables passed through

Response Codes

Message Code	Reason	Description
2	segment name already exists	The name of the new static segment already exists for this account.
2	not all variables passed through	The POST message is missing required elements.

Response Code	Response Text	Description
401	group added	A new static segment (a.k.a. group) was added to your account.
405	not all variables passed through	Not all required elements were included in the request. Review the documentation for this method for the conditional elements.
406	group name already exists	The value provided in the <groupname> element already exists for your account.
428	Missing variables	A required variable is missing from the input.

Example Post

Example Response

Example Error

---