使用MailGun API发送.ics日历邀请，Outlook显示异常的解决方法

期望显示完整的日历邀请卡片（包含接受/拒绝/暂定按钮及活动详情），当前通过MailGun API发送的ICS内容在Gmail中显示正常，但在Outlook客户端无法正常渲染。

现有代码 #

生成ICS内容的PHP代码 #

// 生成ICS文件内容
$ics_content = "BEGIN:VCALENDAR\r\n"
            . "VERSION:2.0\r\n"
            . "PRODID:-//Service Provider Inc//NONSGML kigkonsult.se iCalcreator 2.18//\r\n"
            . "CALSCALE:GREGORIAN\r\n"
            . "METHOD:REQUEST\r\n"
            . "X-WR-TIMEZONE:$timezone\r\n"
            . "BEGIN:VEVENT\r\n"
            . "UID:$uid\r\n"
            . "ATTENDEE;CUTYPE=INDIVIDUAL;ROLE=REQ-PARTICIPANT;PARTSTAT=NEEDS-ACTION;RSVP=TRUE;CN=$fname $lname:MAILTO:$email\r\n"
            . "DESCRIPTION:$ical_desc\r\n"
            . "DTSTART:$dateFrom\r\n"
            . "DTEND:$dateTo\r\n"
            . "DTSTAMP:$currentDate\r\n"
            . "LOCATION:$location\r\n"
            . "ORGANIZER;CN=$organizer_name:MAILTO:$replyTo\r\n"
            . "SEQUENCE:0\r\n"
            . "SUMMARY:$summary\r\n"
            . "BEGIN:VALARM\r\n"
            . "ACTION:DISPLAY\r\n"
            . "DESCRIPTION:REMINDER\r\n"
            . "TRIGGER;RELATED=START:-PT00H15M00S\r\n"
            . "END:VALARM\r\n"
            . "END:VEVENT\r\n"
            . "END:VCALENDAR\r\n";

MailGun API请求代码 #

$domain = $data['domain'];
$api_key = $data['api_key'];
$from = $data['from'];
$to = $data['to'];
$subject = $data['subject'];
$body = $data['body'];

$ics_content = isset($data['ics_content']) ? $data['ics_content'] : null;
$attachments = $ics_content;

$request = $this->httpClient->request('POST', "https://api.mailgun.net/v3/{$domain}/messages",[
    'auth' => ['api', $api_key],
    RequestOptions::MULTIPART => [
        [
            'name' => 'from',
            'contents' => $from,
        ],
        [
            'name' => 'to',
            'contents' => $to,
        ],
        [
            'name' => 'subject',
            'contents' => $subject,
        ],
        [
            'name' => 'html',
            'contents' => "<html>{$body}</html>",
        ],
        [
            'name' => 'attachment', // 附件参数名
            'contents' => base64_decode($attachments), // ICS内容
            'filename' => 'invite.ics', // 附件文件名
        ],
    ],
]);

$statusCode = $request->getStatusCode();
$response_data = json_decode($request->getBody()->getContents(), true);

解决方法（针对Outlook兼容） #

1. 修复附件内容处理逻辑 #

原代码中对ICS内容执行了base64_decode，但$attachments是直接生成的字符串而非Base64编码内容，解码会破坏ICS结构。直接使用原始字符串并添加正确的MIME类型头：

[
    'name' => 'attachment',
    'contents' => $attachments, // 移除base64_decode
    'filename' => 'invite.ics',
    // 添加Outlook识别日历邀请必需的MIME头
    'headers' => [
        'Content-Type' => 'text/calendar; charset=utf-8; method=REQUEST'
    ],
],

2. 确保日期格式符合RFC 5545标准 #

Outlook对日期格式要求严格，必须使用UTC带Z后缀或带时区偏移的格式：

• 错误示例：20240520T100000（无时区信息）
• 正确示例：20240520T100000Z（UTC时间）或20240520T100000+0800（东八区）
  确保$dateFrom、$dateTo、$currentDate都符合此格式。

3. 处理ICS行长度限制 #

RFC 5545要求ICS每行不超过75字符，超过需折叠（在75字符后添加\r\n ，注意空格）。可添加折叠函数处理长字段：

// 折叠ICS长文本的工具函数
function foldIcsLine($line) {
    $maxLength = 75;
    $lines = [];
    while (strlen($line) > $maxLength) {
        $lines[] = substr($line, 0, $maxLength);
        $line = ' ' . substr($line, $maxLength);
    }
    $lines[] = $line;
    return implode("\r\n", $lines);
}

// 对长字段应用折叠
$ical_desc = foldIcsLine($ical_desc);
$location = foldIcsLine($location);

4. 验证组织者身份一致性 #

Outlook会验证ICS中ORGANIZER的邮箱地址与邮件发件人from地址是否一致，确保两者匹配，避免被判定为无效邀请。

5. 检查ICS语法有效性 #

使用ICS标准验证工具检查内容是否符合RFC规范，修复语法错误（如缺少必填字段、格式错误等）。

内容的提问来源于stack exchange，提问作者Bishal Deb