Webservice方法-SendMailListRequestByGroup接口
介绍
调用本接口可以向系统中某个组发送邮件;
方法声明如下:
public EaseyeReturnDTOSendMailListRequestByGroup( EaseyeUserAccountDTO easeyeUserAccountDTO, EaseyeMessageTemplateDTO easeyeMessageTemplateDTO, EaseyeGroupDTO easeyeGroupDTO,EaseyeSendOptionDTO easeyeSendOptionDTO)
输入
- EaseyeUserAccountDTO:easeyeUserAccountDTO
- 用户帐户信息(必填),其字段详细信息如下:
Index | Field | Type | Desc | 最佳实践 |
---|---|---|---|---|
1 | string(50) | 用户名(必填) | 登录名 | |
2 | Password | string(50) | 密码(必填) | 接口密码(不是人工登录密码) |
注:1)Email是用户名,也就是平台的登录帐号;
- EaseyeMessageTemplateDTO:easeyeMessageTemplateDTO
- 待发送的模板信息(必填),其字段详细信息如下:
Index | Field | Type | Desc | 最佳实践 |
---|---|---|---|---|
1 | TemplateName | string(100) | 模板名称(必填) | 建议和任务名称一致,保持唯一性 |
2 | Subject | string(100) | 邮件主题 | 根据用户传入填写 |
3 | Body | string(8000) | 邮件内容 | 根据用户传入填写 |
4 | HasAD | Bool | 主题是否加AD | 设置为“true” |
5 | HasSysBody | Bool | 邮件内容是否加退订标记 | 设置为“true” |
6 | AttachmentUrl | string(不限) | 附件的绝对URL路径(不建议使用附件) | 不填,或者设置为空"" |
7 | TrackLink | string | 是否对当前传入的模板进行跟踪, 本字段为1时表示需要跟踪;不传本字段, 或者本字段为其他值表示不对模板链接进行处理; |
设置为“1” |
8 | IsBodyHtml | string | 是否为HTML格式 | 设置为“1” |
注:1)如果想复用系统已有的模板,TemplateName字段填写待复用的模板名称,其他字段均不填;
2)如果想更改已有的模板,TemplateName字段填写待更改的模板名称,其他字段均需要填写对应的值(相当于新建模板);
3)如果某个模板正在使用中(某个列表正在使用该模板发送),我们不允许更改模板,但允许复用该模板(不填body字段);
4)如果需要跟踪模板,可以设定TrackLink值为1;如果传入的模板已经是跟踪过的,或者不需要跟踪,可以不设定本字段;
5)邮件模板格式是否为HTML格式:如果IsBodyHtml等于数字(字符串)“1”,则是HTML格式。如果该字段设置为其他值,则是非HTML格式。
- EaseyeGroupDTO:easeyeGroupDTO
- 待发送的联系组(必填),其字段详细信息如下:
Index | Field | Type | Desc | 最佳实践 |
---|---|---|---|---|
1 | GroupName | string(50) | 组名,可以用分号分割传递多个组名(必填) | 调用导入联系人接口时设置的联系组名 |
2 | RepulsionGroupName | String(max) | 用来传递排斥组的名字,可以用分号分割传递多个组名。(选填) | 不填,或者填写为空"" |
- EaseyeSendOptionDTO:easeyeSendOptionDTO
- 发送相关的选项(必填),其字段详细信息如下:
Index | Field | Type | Desc | 最佳实践 |
---|---|---|---|---|
1 | MailProjectName | String(256) | 项目名称 | 不填,或者填写为空“” |
2 | MailListtName | String(256) | 列表名称(必填) | 设置为任务名称,请确保唯一 |
3 | SenderName | String(100) | 发送方名称(建议填写) | 根据配置填写 |
4 | SenderEmail | String(100) | 发送方地址(必填) | 根据配置填写 |
5 | ReplyTo | String(50) | 回复地址 | 根据配置填写 |
6 | IsActive | Bool | 是否激活(只有激活才能发送)(必填) | 设置为"true" |
7 | ScheduleSendTime | String(不限) | 计划发送时间 | 不填,或者根据管理员传入值填写 |
8 | IsSendOnce | String | 本列表名称是否仅使用一次 1:仅使用一次;不传本字段,或者本字段为 其他值表示本列表名称允许重复使用; |
设置为“1” |
9 | CustomDomain | String | 用户自定义域名。 如果选择了跟踪邮件中的链接, 则链接中的域名会被替换成该自定义域名 |
不填,或者填写为空"" |
10 | TopicName | String | 栏目名称 | 不填,或者填写为空"" |
11 | contactLiveNew | String | 是否启用新版活跃度。 输入值1(启用)或0(不启用) |
填写为“0” |
12 | ExpirationDate | String | 列表过期时间点,必须比发送时间晚4个小时, 格式为“yyyy-MMddThh:mm:ss”其中, 各个数值所占位数必须符合格式定义,不足则补0, 比如“2012-07-03T03:23:01” |
不填,或者根据管理员传入值填写 |
13 | MailListPrecedenceBase | String | 发送列表优先级,可以设定为以下值: 0、1、2,分别表示普通、中、高三个优先级别 |
不填,或者填写为“0” |
注:1)如果列表名称为本次发送的名称,您需要使用它来查询后续的报表,所以我们建议您尽量不要使用重复的列表名称;
2)发送方地址(SenderEmail)必须在平台验证通过方可使用,您可以登录平台后,在”我的配置”的”添加验证更多地址”中,添加您想使用的发送方地址;
3)计划发送时间如果不填写或者填写的值小于系统当前时间,视为立刻发送;如果您需要定时发送,该字段的格式为”yyyy-MM-dd hh:mm:ss”;
4)IsSendOnce是用来防止异常情况下的重复发送或者遗漏发送的;主要用于以下场景:如果您提交了一次发送,但是,提交请求过程中,网络异常中断;
当网络恢复时,您无法确定您上次提交是否成功;出于这种考虑,您可以将这个字段一直设置为1;提交后我们会检查该列表名称是否有发送历史,如果有,
那么,本次发送就不会进行(返回成功);如果没有,本次发送就会进行(根据进行结果返回成功失败);
5)CustomDomain必须是用户在平台上已经添加的。该域名会在发送邮件时替换默认的链接。
6)TopicName必须是在平台上已经添加的。且用户开通栏目功能。
处理
首先创建或者更改或者加载模板,最后创建列表,关联所需要发送的组后发送;
- 如果模板名称不存在,则创建模板;如果模板名称存在,且body字段非空,则根据当前信息更新模板(该模板不能在使用中);如果模板名称存在,且body字段为空,则加载已有模板;
- 如果对应的组不存在或者组中的联系人为空,系统会返回临时错误(4xx);
- 如果创建列表激活时,发现点数不足,系统会返回临时错误(4xx);
输出
- EaseyeReturnDTO
- 邮件发送返回信息,其字段详细信息如下:
Index | Field | Type | Desc |
---|---|---|---|
1 | ErrorCode | Int | 错误码,3位整数 2xx:处理成功; 3xx:部分成功; 4xx:临时错误; 5xx:永久错误 |
2 | ErrorInfo | string | 发生临时错误和永久 错误时,携带失败的原因 |
注:1)判断是否成功的标准取决于ErrorCode,其取值范围和取值含义见它的描述;
2)一般来说,临时失败(4xx)建议等待一个随机时间后重试,可设定最大重试次数;
重试若干次如果仍然失败,通知管理员联系我方,同时将ErrorInfo的值记录下来,一并告知我方;
3)永久失败(5xx)不建议重试,发生5xx时,通知管理员联系我方,同时将ErrorInfo的值记录下来,一并告知我方;
- 常见调用失败情况
- (4xx):点数不足;
- (4xx):模板或者列表正在使用中(试图更改一个模板或者列表);
- (4xx):待发送的组不存在或者该组中无联系人;
- (4xx):数据库操作失败;
- (5xx):某个字段长度不符合定义;
- (5xx):某个必须的字段缺失;
- (5xx):联系人Email地址格式校验不通过;