SendGrid에서 옮기기
SendGrid SDK는 그대로 두고 OpenEmail을 통해 보냅니다. 기본 URL과 키만 바꾸면 보내는 코드는 그대로입니다.
바꿀 것
SDK가 https://api.openemail.uk/compat/sendgrid를 가리키게 하고, SendGrid 키 대신 emails:send 권한이 있는 OpenEmail API 키를 주세요. 키는 같은 Authorization: Bearer 헤더로 전달됩니다. 메일을 보내는 호출은 그대로이며, 메시지가 나갈 수 있는지는 OpenEmail의 다른 모든 곳과 마찬가지로 From 주소가 정합니다.
import sgMail from '@sendgrid/mail'import client from '@sendgrid/client' client.setApiKey(process.env.OPENEMAIL_API_KEY)client.setDefaultRequest('baseUrl', 'https://api.openemail.uk/compat/sendgrid')sgMail.setClient(client) await sgMail.send({ from: '[email protected]', to: '[email protected]', subject: 'Your invoice', html: '<p>Your invoice is attached.</p>',})Node에서는 먼저 클라이언트에 키를 설정하고, 다음으로 기본 URL을 설정한 뒤, 그 클라이언트를 메일 패키지에 넘기세요. 그 뒤에 sgMail.setApiKey를 호출하지 마세요. 기본 URL이 SendGrid로 되돌아갑니다. SDK가 키가 SG.로 시작하지 않는다고 경고하지만 문제없습니다. Python, Ruby, PHP에서는 호스트 끝에 슬래시를 붙이지 마세요.
무엇이 무엇에 대응하나
제공하는 엔드포인트는 POST /v3/mail/send입니다. personalizations의 각 항목은 자기 ID를 가진 별도의 OpenEmail 메시지가 되므로, 요청 하나로 최대 100통을 보냅니다.
| SendGrid | OpenEmail에서 |
|---|---|
| from | 발신자와 그 이름. 개인화마다 자기 from을 지정할 수 있습니다. |
| personalizations | 개인화마다 메시지 한 통입니다. 그 to, cc, bcc는 합쳐서 최대 50명의 수신자를 담고, 그 subject, headers, custom_args, send_at, substitutions는 그 메시지에만 적용됩니다. |
| subject | 제목. 개인화가 자기 제목을 정하면 그것을 씁니다. |
| content | text/plain은 텍스트 본문이 되고 text/html은 HTML 본문이 됩니다. HTML 본문이 이미 메시지를 전하므로 text/x-amp-html은 빠집니다. |
| attachments | 파일은 최대 20개, 합계 5MB까지. HTML이 cid:로 content_id를 참조하는 인라인 이미지는 그 자리에 삽입됩니다. 그 밖의 인라인 파일은 일반 첨부로 도착합니다. |
| reply_to | 회신 주소. reply_to_list도 주소가 하나뿐이면 동작합니다. |
| headers | 사용자 지정 헤더: X-*, List-*, Reply-To, Precedence, Auto-Submitted, Importance, Priority, Feedback-ID. 개인화는 자기 헤더를 더합니다. |
| categories | category, category_2처럼 이어지는 이름의 태그로, 각각 카테고리 하나를 담습니다. |
| custom_args | 같은 이름과 값을 가진 태그. 개인화의 값이 우선합니다. |
| send_at | 예약 발송으로, 최대 1년 뒤까지. 이미 지난 시각이면 바로 보냅니다. |
| substitutions | 각 키는 그 메시지의 제목, 텍스트 본문, HTML 본문에서 값으로 바뀝니다. |
| template_id | OpenEmail 템플릿의 ID(tpl_...) 또는 슬러그로, dynamic_template_data의 값으로 채워집니다. |
| tracking_settings | open_tracking.enable과 click_tracking.enable이 그 메시지의 열람 추적과 클릭 추적을 켜거나 끕니다. |
| mail_settings | sandbox_mode.enable은 요청, 발신자, 템플릿을 검사한 다음 아무것도 보내지 않고 200으로 응답합니다. |
메시지 한 통에는 카테고리와 custom_args를 합쳐 최대 10개의 태그가 붙습니다. 더 필요한 요청은 잘라 내지 않고 거부하므로, 보낸 내용이 말없이 사라지지 않습니다.
거부되는 것과 그 이유
template_id에 넣은d-…같은 SendGrid 템플릿 ID. 템플릿은 SendGrid에 남으므로, OpenEmail에서 템플릿을 다시 만들고 그 ID나 슬러그를 보내세요.template_id와 함께 쓴content. OpenEmail 템플릿이 본문 전체를 제공하기 때문입니다. 같은 이유로 템플릿과 함께 쓴substitutions도 거부됩니다. 값은dynamic_template_data로 넘기세요.- 두 개 이상의 회신 주소, 함께 쓴
reply_to와reply_to_list, 텍스트와 HTML이 아닌 콘텐츠 유형. 캘린더 초대는.ics첨부로 보내세요. - 켜 둔
mail_settings.footer와sections. OpenEmail은 메시지에 글을 덧붙이지 않기 때문입니다. - 10개를 넘는 태그, 영문자·숫자·
_·-외의 문자가 들어간 태그 이름, 위 목록에 없는 헤더, 요청 하나에 100개를 넘는 개인화.
asm, batch_id, ip_pool_name, mail_settings의 우회 설정, subscription_tracking, ganalytics, click_tracking.enable_text, open_tracking.substitution_tag는 받아들이지만 아무것도 바꾸지 않습니다. 워크스페이스 차단 목록에 있는 주소는 우회 설정과 상관없이 항상 건너뜁니다.
응답과 오류
- 발송은 빈 본문으로 202를 응답하고
X-Message-Id에 OpenEmail 메시지 ID를 담습니다.GET /emails/{id}와 웹훅이 쓰는 그 ID입니다. 개인화가 여러 개면 첫 메시지의 ID가 담깁니다.Idempotency-Key헤더는 API의 다른 곳과 똑같이 동작합니다. - 오류는
message,field,help의 목록인errors로 돌아옵니다. 보낼 수 없는 요청은 400, 키가 없거나 알 수 없으면 401,emails:send가 없는 키나 키가 쓸 수 없는 From 주소, 도메인이 아직 보낼 수 없는 From 주소는 403, 30MB를 넘는 본문이나 5MB를 넘는 첨부는 413, 워크스페이스가 발송 한도를 다 쓴 경우는 429입니다. - 앞선 개인화가 받아들여진 뒤 하나가 실패하면, 오류가 이미 보낸 메시지를 알려 주므로 재시도할 때 그것들을 뺄 수 있습니다.