xWeb Email Opt Out

This page contains some general information about email opt outs in NetForum.

Pulling a List of Customers with a Query

Be sure to consider the following:

Opt-out preferences
Overall customer do not mail flag is 0 (cst_no_email_flag)
Individual deceased flag is 0 (ind_deceased_flag)
Individual soft delete flag is 0 (ind_delete_flag)
co_email.eml_invalid_flag is set to 0 (that is, email address is valid)

Do Not Email Flag

NetForum contains a global Do Not Contact by Email flag for customers who don't want any mailings. The one exception is that that the customer will still get a confirmation email if they make a purchase or initiate some other activity.

NetForum automatically suppresses these customers from mass emails generated from within the product.

If a list of customers is pulled independently of a mailing, however, (for example, from a query), the query should be written to exclude these customers, but it's possible for the user writing the query to forget this or not know about the flag. Therefore, to keep a list of customers who have opted out of all mass emails, the following GetQuery will give you the list of email addresses and customers who have opted out. Be sure to select only the fields you need.

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.avectra.com/2005/">
<soapenv:Header>
<ns:AuthorizationToken>
<ns:Token>*******************</ns:Token>
</ns:AuthorizationToken>
</soapenv:Header>
<soapenv:Body>
<ns:GetQuery>
<ns:szObjectName>IndividualEmail</ns:szObjectName>
<ns:szColumnList>eml_address, eml_cst_key</ns:szColumnList>
<ns:szWhereClause>cst_no_email_flag=1</ns:szWhereClause>
<ns:szOrderBy></ns:szOrderBy>
</ns:GetQuery>
</soapenv:Body>
</soapenv:Envelope>

Response

Note that email addresses can be duplicated.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Header>
<AuthorizationToken xmlns="http://www.avectra.com/2005/">
<Token>f8ab7fa0-f644-4390-86f0-5a41e3391be3</Token>
</AuthorizationToken>
</soap:Header>
<soap:Body>
<GetQueryResponse xmlns="http://www.avectra.com/2005/">
<GetQueryResult>
<IndividualEmailObjects xsi:schemaLocation="http://www.avectra.com/2005/ IndividualEmail.xsd" recordReturn="4">
<IndividualEmailObject>
<eml_key>2c19596b-d6e9-48f9-b5aa-0b854c6bb441</eml_key>
<eml_address>skatragadda@avectra.com</eml_address>
<eml_cst_key>3de68bfc-1ff5-4bfa-8acf-95d35a81c1bf</eml_cst_key>
</IndividualEmailObject>
<IndividualEmailObject>
<eml_key>5f9ef513-c709-481d-b953-1ef9920e7b6a</eml_key>
<eml_address>cfozoh@avectra.com</eml_address>
<eml_cst_key>4a70bcae-be72-4c0b-987e-06247fb0b26b</eml_cst_key>
</IndividualEmailObject>
<IndividualEmailObject>
<eml_key>2d8ba584-6e86-42ea-a3aa-3d9b4275afd4</eml_key>
<eml_address>skatragadda@avectra.com</eml_address>
<eml_cst_key>4d4723a6-b2b2-4653-9d44-4c8541d77419</eml_cst_key>
</IndividualEmailObject>
<IndividualEmailObject>
<eml_key>f4e26e1a-8705-4c56-86b0-59b6bf17c673</eml_key>
<eml_address>joaninst@mailinator.com</eml_address>
<eml_cst_key>f84a4296-0292-4de2-ab8f-11026c5804f8</eml_cst_key>
</IndividualEmailObject>
</IndividualEmailObjects>
</GetQueryResult>
</GetQueryResponse>
</soap:Body>
</soap:Envelope>

Get Email Opt Out Setting for Single Customer

Request

This example returns the no-email-flag, as well as the customer key. You could also use the integer ID (cst_recno) instead of customer key.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.avectra.com/2005/">
<soapenv:Header>
<ns:AuthorizationToken>
<ns:Token>**************</ns:Token>
</ns:AuthorizationToken>
</soapenv:Header>
<soapenv:Body>
<ns:GetQuery>
<ns:szObjectName>Customer</ns:szObjectName>
<ns:szColumnList>cst_no_email_flag</ns:szColumnList>
<ns:szWhereClause>cst_key='237934C6-305E-4A62-879E-501A35398C8F'</ns:szWhereClause>
<ns:szOrderBy></ns:szOrderBy>
</ns:GetQuery>
</soapenv:Body>
</soapenv:Envelope>

Response

cst_no_email_flag of "1" means they do not want emails; 0 means they have NOT specified no emails.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Header>
<AuthorizationToken xmlns="http://www.avectra.com/2005/">
<Token>b1ae0ee6-39d4-4d87-a3a7-62f3cf430052</Token>
</AuthorizationToken>
</soap:Header>
<soap:Body>
<GetQueryResponse xmlns="http://www.avectra.com/2005/">
<GetQueryResult>
<CustomerObjects xsi:schemaLocation="http://www.avectra.com/2005/ Customer.xsd" recordReturn="1">
<CustomerObject>
<cst_key>237934c6-305e-4a62-879e-501a35398c8f</cst_key>
<cst_no_email_flag>0</cst_no_email_flag>
</CustomerObject>
</CustomerObjects>
</GetQueryResult>
</GetQueryResponse>
</soap:Body>
</soap:Envelope>

Get Email Opt Out Setting for Multiple Customers

Request

If you have multiple customer keys then you can specify a list as shown. This is essentially the same as the request above but you are using the "IN" operator to specify a list of keys. The list of keys must be enclosed in parentheses and each key must be separated by a comma. You could also use the integer ID (cst_recno) instead of customer key.

Note: If you are trying to get this information for thousands of customers, then you should probably not send a list of thousands of IDs in the szWhereClause. Instead, break out your list into smaller chunks of 50, 100 or 200 at a time.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.avectra.com/2005/">
<soapenv:Header>
<ns:AuthorizationToken>
<ns:Token>**********</ns:Token>
</ns:AuthorizationToken>
</soapenv:Header>
<soapenv:Body>
<ns:GetQuery>
<ns:szObjectName>Customer</ns:szObjectName>
<ns:szColumnList>cst_no_email_flag</ns:szColumnList>
<ns:szWhereClause>cst_key IN ('237934C6-305E-4A62-879E-501A35398C8F', '77EF0279-0F2F-4DF7-ABBB-3166D9FA1E7A',
'0F23AFD5-24AB-4B64-A6BB-233BE3214DCD', '68B88984-6C05-4FE0-B3F2-CFE24A9A130B')</ns:szWhereClause>
<ns:szOrderBy></ns:szOrderBy>
</ns:GetQuery>
</soapenv:Body>
</soapenv:Envelope>

Response

Notice the 3rd record is opted-out (1) but the others are opted-in (0).

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Header>
<AuthorizationToken xmlns="http://www.avectra.com/2005/">
<Token>973f42f5-0986-4382-a051-bf555f810c43</Token>
</AuthorizationToken>
</soap:Header>
<soap:Body>
<GetQueryResponse xmlns="http://www.avectra.com/2005/">
<GetQueryResult>
<CustomerObjects xsi:schemaLocation="http://www.avectra.com/2005/ Customer.xsd" recordReturn="4">
<CustomerObject>
<cst_key>0f23afd5-24ab-4b64-a6bb-233be3214dcd</cst_key>
<cst_no_email_flag>0</cst_no_email_flag>
</CustomerObject>
<CustomerObject>
<cst_key>77ef0279-0f2f-4df7-abbb-3166d9fa1e7a</cst_key>
<cst_no_email_flag>0</cst_no_email_flag>
</CustomerObject>
<CustomerObject>
<cst_key>237934c6-305e-4a62-879e-501a35398c8f</cst_key>
<cst_no_email_flag>1</cst_no_email_flag>
</CustomerObject>
<CustomerObject>
<cst_key>68b88984-6c05-4fe0-b3f2-cfe24a9a130b</cst_key>
<cst_no_email_flag>0</cst_no_email_flag>
</CustomerObject>
</CustomerObjects>
</GetQueryResult>
</GetQueryResponse>
</soap:Body>
</soap:Envelope>

Alternate Request for Email Opt-Out for Multiple Customers

If the only thing you want to know is who is opted out from among a specific list of customers, then you can improve the performance of the query above by returning only customers who are actually opted-out, because there is no point in returning customers who are opted-in. You can also trim the payload by returning only the customer key, since you will know that any customers that are returned are opted-out based on the filter. Notice how the szWhereClause includes the AND cst_no_email_flag=1 condition.

Put another way, if you want to know which of 100 customers are opted out, then you don't need to get back a return of all 100 customers with a 1/0 setting; you just want to get back the smaller list of customers who actually are opted-out.

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.avectra.com/2005/">
<soapenv:Header>
<ns:AuthorizationToken>
<ns:Token>**************</ns:Token>
</ns:AuthorizationToken>
</soapenv:Header>
<soapenv:Body>
<ns:GetQuery>
<ns:szObjectName>Customer</ns:szObjectName>
<ns:szColumnList>cst_key</ns:szColumnList>
<ns:szWhereClause>cst_key IN ('237934C6-305E-4A62-879E-501A35398C8F', '77EF0279-0F2F-4DF7-ABBB-3166D9FA1E7A',
'0F23AFD5-24AB-4B64-A6BB-233BE3214DCD', '93ee52f4-ad89-493f-af9b-826c66a17420', '0D3C0195-3839-4991-BFF5-B8EF4AC93811', '68B88984-6C05-4FE0-B3F2-CFE24A9A130B') AND cst_no_email_flag=1</ns:szWhereClause>
<ns:szOrderBy></ns:szOrderBy>
</ns:GetQuery>
</soapenv:Body>
</soapenv:Envelope>

Response

In the request, you asked for 6 customers keys. In the response, you got back the two who are opted-out. The other 4 are not opted-out, so they are not in the return list; you will need to make sure you reconcile your original list of customers that you are querying against, with the results of these queries.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Header>
<AuthorizationToken xmlns="http://www.avectra.com/2005/">
<Token>1b1f116d-3d73-4bd0-8a69-92dc1d86c1da</Token>
</AuthorizationToken>
</soap:Header>
<soap:Body>
<GetQueryResponse xmlns="http://www.avectra.com/2005/">
<GetQueryResult>
<CustomerObjects xsi:schemaLocation="http://www.avectra.com/2005/ Customer.xsd" recordReturn="2">
<CustomerObject>
<cst_key>93ee52f4-ad89-493f-af9b-826c66a17420</cst_key>
</CustomerObject>
<CustomerObject>
<cst_key>0D3C0195-3839-4991-BFF5-B8EF4AC93811</cst_key>
</CustomerObject>
</CustomerObjects>
</GetQueryResult>
</GetQueryResponse>
</soap:Body>
</soap:Envelope>

Notes:

If you want to tune this even more for performance, than consider this approach. First, find out daily how many customers in a particular site actually are opted-out. If the number of opt-outs is relatively small (less than 1,000?), and you are working through a large list of customers in a large query (50,000 or more?), then rather than querying to see which of those 50,000 are opted-out, then it might be faster to just run one query to get a list of all opted-out customers, and reconcile your list that way. The actual numbers in this illustration are starting points; YMMV.
You could squeeze the message size of the SOAP request down even further by using cst_recno (which is shorter) instead of cst_key (which is 36 characters long). Internally, NetForumcan run a query based on cst_recno just as fast as cst_key, so if you have both fields readily available then you can compose shorter requests by using cst_recno in the szWhereClause. netFORUM will return the cst_key in the response all the time, however, so you will need to interpret it that way. You can, however, request to also return cst_recno by adding it to the szColumnList, if desired.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.avectra.com/2005/">
<soapenv:Header>
<ns:AuthorizationToken>
<ns:Token>****************</ns:Token>
</ns:AuthorizationToken>
</soapenv:Header>
<soapenv:Body>
<ns:GetQuery>
<ns:szObjectName>Customer</ns:szObjectName>
<ns:szColumnList>cst_key</ns:szColumnList>
<ns:szWhereClause>cst_recno IN (88468,88469,88470,88471,88472,88474,88475,88476) AND cst_no_email_flag=1</ns:szWhereClause>
<ns:szOrderBy></ns:szOrderBy>
</ns:GetQuery>
</soapenv:Body>
</soapenv:Envelope>

Setting the Do Not Mail Flag

If you want to set the global Do Not Contact by Email flag for a single customer then run the following UpdateFacadeObject method. Pass the value of the customer's customer key into the szObjectKey parameter in the request. Set the cst_no_email_flag to 1 to opt-out, or 0 to not opt-out.

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.avectra.com/2005/">
<soapenv:Header>
<ns:AuthorizationToken>
<ns:Token>*************</ns:Token>
</ns:AuthorizationToken>
</soapenv:Header>
<soapenv:Body>
<ns:UpdateFacadeObject>
<ns:szObjectName>Individual</ns:szObjectName>
<ns:szObjectKey>9e64ee86-a866-4117-98e4-4bde03338a3c</ns:szObjectKey>
<ns:oNode>
<ns:IndividualObjects>
<ns:IndividualObject>
<ns:cst_no_email_flag>1</ns:cst_no_email_flag>
</ns:IndividualObject>
</ns:IndividualObjects>
</ns:oNode>
</ns:UpdateFacadeObject>
</soapenv:Body>
</soapenv:Envelope>

Caching Mailing Types

The sample for this method contains sample data. Do not assume that the specific data you see on this page, particularly the keys, are the same data that will exist in the netFORUM site in which you're developing an integration. Moreover, if you are developing an integration that will work against multiple netFORUM sites for multiple customers, be aware that the data for each customer, including setup data, will differ. See netFORUM Data for more information.

Information about Mailing Types rarely changes. We recommend you cache the result for mailing types and get a new list on a regular interval, especially in a high-traffic application that calls this method frequently. For more information, see Data Caching.