灵动创新 Unimarketing 邮件营销 EDM

SMTP API文档

1. 入口

  • 地址:smtp.unimarketing.org 端口:25和2525(SMTP)
  • 地址:services.unimarketing.org 端口:465(SMTPS)

2. SMTP帐户密码

  • 从“系统设置”->“API Key 管理”获取SMTP帐户密码:
    • SMTP 帐户:{Consumer Key}
    • SMTP 密码:{Consumer Secret}

3. SMTP信头参数

  • 信头参数列表:
  • 信头 说明 备注
    X-Qos 邮件类型
    transactional缺省为触发邮件不用设置此参数
    bulk非触发交易邮件
    X-Campaign 邮件名称 指定本次发送所采用的邮件名称,如果邮件名称不存在,则会自动创建。
    X-List 联系人列表 指定将邮件发送者添加到的联系人列表。如果联系人列表不存在,则会创建。
    X-Tracking-ID 用户自定义
    文本标识
    灵动平台在处理完投递后,可以通过Webbook传回的消息中获取该数据。每个标识最长60个字符,当一次调用发送多封邮件时,请用逗号分割。
    X-Tracking-Data 用户自定义
    文本数据
    获取方式同上,文本数据格式不限,最长1000字符

4. 要求和限制

  • 1. X-List和X-Campaign长度不能大于200个字符,如果包含中文,需要使用BASE64编码(B编码);
  • 2. X-Campaign每天新建数据限制在50个以内,超过限制,会返回如下响应:
    550 Too many campaign today. Please try again the next day 
    注:第二天解除限制
  • 3. 发件人和收件人地址长度限制在50个字符以内;
  • 4. 发件人名称长度限制在50个字符以内,主题长度限制在200个字符以内;
  • 5. 每次调用只能填写五个邮件接收人地址,多于五个时,则不会处理这次调用,会返回如下响应:
    452 Too many recipients to the message, Please reduce the number of recipients less than or equal to 5 recipients and retry
  • 6. 正文内容(含HTML代码)大小限制在64KB以内,附件合计大小限制在5MB以内;
  • 7. 触发邮件(如密码找回)和营销邮件(如情人节促销通知)将使用不同的处理流程和优先级,为了避免触发邮件与营销邮件相互干扰,请一定要为营销邮件添加X-Qos值为“bulk”的信头
  • 8. 如果您想对API邮件中的链接点击数据进行追踪,请在邮件a标签中添加非完全数字类型的link属性,例如:
    <a href="http://www.website.com" link="site_1" ...
    注:不同链接的link属性值不能重复,如果重复则视为同一个链接,这些链接的点击数据会合并在一起统计
  • 9. 为了优化联系人体验,您需要在邮件中添加退订系统链接,以方便联系人进行退订,降低联系人直接向ISP投诉导致发送信誉度降低的风险。

5. 调用响应示例

  • 1. 响应正文示例(单封邮件):正常调用
    250 ok: Message 22201212005849505.27832346.23084.18674 accepted
    
  • 2. 响应正文示例(单封邮件):含有警告信息
    250 ok: Message 22201212005849505.27832346.23084.18674 accepted, Warnning : recipients quota reached
    
  • 3. 响应正文示例(多封邮件):
    250 ok: Message 22201212005849505.27832346.23084.18674 and left 18 messages accepted
    
  • 4. 响应正文示例(多封邮件):含有警告信息
    250 ok: Message 22201212005849505.27832346.23084.18674 and left 25 messages accepted, Warnning : recipients quota reached
    
  • 5. 响应正文示例(多封邮件):含有警告信息和无效地址提示
    250 ok: Message 22201212005849505.27832346.23084.18674 and left 25 messages accepted, Warnning : recipients quota reached; invalid mailbox ignowntipt@mail.ru is unavailable. http://www.unimarketing.com.cn/help/about_delivery.html#bad-mailbox
    
  • 6. 响应正文示例(多封邮件):含有警告信息和退订地址提示(退订只针对营销邮件)
    250 ok: Message 22201606019253710.47039368.95477.66283 and left 2 messages accepted, Warnning : messages quota reached, unsubscribed mailbox 370049196@qq.com is unavailable
    
  • 备注:
    上面正文中"22201606019253710"是这次调用唯一标识,结合Webhook可以追踪这封邮件的投递送达状态,邮件的打开点击等用户行为
    

6. 调用示例

  • 1. Java调用示例:
    import java.util.Properties;
    import javax.activation.DataHandler;
    import javax.activation.DataSource;
    import javax.activation.FileDataSource;
    import javax.mail.Authenticator;
    import javax.mail.Message;
    import javax.mail.PasswordAuthentication;
    import javax.mail.Session;
    import javax.mail.Transport;
    import javax.mail.internet.AddressException;
    import javax.mail.internet.InternetAddress;
    import javax.mail.internet.MimeBodyPart;
    import javax.mail.internet.MimeMessage;
    import javax.mail.internet.MimeMultipart;
    import javax.mail.internet.MimeUtility;
    import org.apache.commons.lang3.StringUtils;
    
    public class MySMTP {
    
    	private static final String SMTP_SERVER = "smtp.unimarketing.org";
    	private static final String APIKey = "您的API Key";
    	private static final String APISecret = "您的API Secret";
    
    	public static void main(String[] args) throws Exception {
    
    		Properties properties = new Properties();
    		properties.put("mail.smtp.host", SMTP_SERVER);
    		properties.put("mail.smtp.auth", "true");
    		properties.put("mail.smtp.port", "25");
    		properties.put("mail.transport.protocol", "smtp");
    
    		String fromAddress    = "no-reply@example.com";
    		String recipient      = "someone@customer.com";
    		String replyTo        = "replyto@customer.com";
    		String subject        = "邮件主题";
    		String fileAttachment = "附件路径";
    		String content        = "邮件正文内容";
    
    		InternetAddress[] receiveAddresses = new InternetAddress[] { new InternetAddress(recipient) };
    
    		Session session = Session.getInstance(properties, new SmtpAuth());
    		session.setDebug(true);
            	session.setDebugOut(new PrintStream("smtp.log"));
    
    		MimeMessage message = new MimeMessage(session);
    		MimeMultipart multipart = new MimeMultipart();
    
    		multipart.setSubType(ContentTypeEnum.ALTERNATIVE.getLabel());
    		MimeBodyPart bodyPart = new MimeBodyPart();
    		bodyPart.setContent(content, "text/html; charset=utf-8");
    		multipart.addBodyPart(bodyPart);
    
    		if (StringUtils.isNotBlank(fileAttachment)) {
    			DataSource dataSource = new FileDataSource(fileAttachment);
    			String name = dataSource.getName();
    			bodyPart = new MimeBodyPart();
    			bodyPart.setDataHandler(new DataHandler(dataSource));
    			bodyPart.setFileName(MimeUtility.encodeText(name));
    			multipart.addBodyPart(bodyPart);
    		}
    
    		message.setSubject(subject);
    		message.setContent(multipart);
    		//设置发件人地址
    		message.setFrom(new InternetAddress(fromAddress));
    		//设置收件人地址,最多5个地址,超过会导致本次调用全部失败
    		message.setRecipients(Message.RecipientType.TO, receiveAddresses);
    		//设置回复地址
    		message.setReplyTo(new InternetAddress(replyTo));
    
    		message.addHeader("X-List", MimeUtility.encodeText("联系人列表名称"));
    		//报表会以这个名称,分别统计数据,建议按照不同用途场景,使用不同的名称,方便识别统计数据
    		message.addHeader("X-Campaign", MimeUtility.encodeText("邮件名称"));
    		//营销邮件需要设置该参数
    		message.addHeader("X-Qos", MimeUtility.encodeText("bulk")); 
    		Transport.send(message);
    
     /**
       *  获取返回信息
       */
            File file = new File("smtp.log");
            BufferedReader reader = null;
    		try {
    			reader = new BufferedReader(new FileReader(file));
    			String tempString = null;
    			while ((tempString = reader.readLine()) != null) {
    				if (tempString.lastIndexOf("250 ok:") != -1) {
    					System.out.println("返回数据为:" + tempString);
    				}
    			}
    			reader.close();
    		} catch (IOException e) {
    			e.printStackTrace();
    		} finally {
    			if (reader != null) {
    				reader.close();
    			}
    		}
    
    		System.out.println("发送成功");
    	}
    	
    	static class SmtpAuth extends Authenticator {
    		
    		public PasswordAuthentication getPasswordAuthentication() {
    			return new PasswordAuthentication(USER_NAME, PASSWORD);
    		}
    	}
    }
    
  • 2. 邮件客户端调用示例:

7. SDK

  • 1. JAVA SDK 下载
    • 1.1 JAVA SDK 主要提供 OAuth 授权DEMO 和 一个客户端工具类
    • 1.2 JAVA SDK 提供所有API 客户端测试DEMO
  • 2. PHP SDK 下载
    • 1.1 PHP SDK 主要提供一个客户端工具类
    • 1.2 PHP SDK 提供所有API 客户端测试DEMO
  • 3. .NET SDK 下载
    • 1.1 .Net SDK 主要提供一个客户端工具类
    • 1.2 .Net SDK 提供所有API 客户端测试DEMO
平台介绍
关于我们 | 联系我们 | 行业应用 | 专业术语 | 资源中心 | 隐私声明
© 2022 灵动创新(北京)科技有限公司 - 京ICP备16028763号-1