Mailgun에서 옮기기
Mailgun SDK는 그대로 두고 OpenEmail을 통해 보냅니다. 기본 URL과 키만 바꾸면 보내는 코드는 그대로입니다.
바꿀 것
SDK가 https://api.openemail.uk/compat/mailgun을 가리키게 하고, Mailgun 키 대신 emails:send 권한이 있는 OpenEmail API 키를 주세요. 키는 같은 HTTP Basic 로그인의 비밀번호로 전달되며, 사용자 이름은 확인하지 않습니다. 경로의 도메인은 워크스페이스 도메인 중 하나여야 하며, 메시지가 나갈 수 있는지는 OpenEmail의 다른 모든 곳과 마찬가지로 From 주소가 정합니다.
import formData from 'form-data'import Mailgun from 'mailgun.js' const mailgun = new Mailgun(formData)const mg = mailgun.client({ username: 'api', key: process.env.OPENEMAIL_API_KEY, url: 'https://api.openemail.uk/compat/mailgun',}) await mg.messages.create('acme.com', { from: 'Acme Billing <[email protected]>', to: ['[email protected]'], subject: 'Your invoice', html: '<p>Your invoice is attached.</p>',})Ruby에서는 두 번째 인수가 스킴 없는 호스트와 경로입니다. PHP에서는 SDK가 전달받은 엔드포인트에서 호스트만 쓰므로, 경로는 php-http의 AddPathPlugin으로 넣습니다. 이 플러그인은 SDK가 이미 설치합니다. 공식 Python 패키지는 호스트가 Mailgun의 것이 아니라는 경고를 로그에 남길 수 있지만, 그래도 보냅니다. 또 429나 5xx로 실패한 요청을 재시도하므로, 배치의 일부가 이미 나간 뒤에는 OpenEmail이 5xx 대신 400으로 응답합니다.
무엇이 무엇에 대응하나
제공하는 엔드포인트는 POST /v3/{domain}/messages이며, 첨부에 필요한 multipart/form-data나 application/x-www-form-urlencoded로 받습니다. 이름이 []로 끝나는 필드는 그것을 뺀 이름으로 읽습니다.
| Mailgun | OpenEmail에서 |
|---|---|
| from | 발신자와 그 이름. |
| to | 수신자. 반복하거나 쉼표로 구분합니다. cc, bcc와 합쳐 메시지당 최대 50명입니다. |
| subject | 제목. |
| html | HTML 본문. text는 텍스트 본문이 되며, 둘 중 하나나 template이 필수입니다. |
| attachment | 파일은 최대 20개, 합계 5MB까지. |
| inline | HTML이 파일 이름으로 cid:를 참조하는 이미지는 그 자리에 삽입됩니다. 그 밖의 인라인 파일은 일반 첨부로 도착합니다. |
| o:tag | tag, tag_2처럼 이어지는 이름의 태그로, 각각 태그 하나를 담습니다. |
| v: | 각 변수는 그 이름과 값을 가진 태그가 됩니다. o:tag와 합쳐 메시지당 최대 10개입니다. |
| o:deliverytime | 예약 발송으로, 최대 1년 뒤까지. 이미 지난 시각이면 바로 보냅니다. |
| o:tracking | o:tracking-clicks, o:tracking-opens와 함께 그 메시지의 추적을 켜거나 끕니다. htmlonly는 켠 것으로 봅니다. |
| o:testmode | yes는 oe_test_ 키처럼, 전달하지 않고 보낸 것으로 기록합니다. |
| h:Reply-To | 회신 주소. 그 밖의 h: 필드는 사용자 지정 헤더가 됩니다: X-*, List-*, Precedence, Auto-Submitted, Importance, Priority, Feedback-ID. |
| recipient-variables | 배치 발송입니다. to의 각 주소가 자기 메시지를 받으며, %recipient.key%는 그 주소의 변수로, %recipient%는 그 주소로 채워지고, cc와 bcc는 각 메시지에 붙습니다. 값이 없는 자리표시자는 그대로 남습니다. |
| template | OpenEmail 템플릿의 슬러그 또는 ID(tpl_...)로, t:variables, 없으면 h:X-Mailgun-Variables의 값으로 채워집니다. t:version은 버전을 번호로 고릅니다. |
거부되는 것과 그 이유
html이나text와 함께 쓴template. OpenEmail 템플릿이 본문 전체를 제공하기 때문입니다. 버전 번호가 아닌t:version도 거부됩니다.o:deliverytime-optimize-period와o:time-zone-localize. OpenEmail은 수신자마다 발송 시각을 고르지 않기 때문입니다. 다른h:X-Mailgun-헤더는 Mailgun에 보내는 지시이므로, 대신 해당하는o:옵션을 쓰세요.- 단독으로 쓴
amp-html.html이나text와 함께면 그것들이 메시지를 전하므로 빠집니다. - 두 개 이상의 회신 주소, 10개를 넘는 태그, 영문자·숫자·
_·-외의 문자가 들어간 태그 이름, 수신자가 100명을 넘는 배치. Mailgun은 1,000명까지 받으므로 더 큰 배치는 나누세요.
o:dkim, o:require-tls, o:skip-verification, o:sending-ip, o:sending-ip-pool, o:tracking-pixel-location-top, o:archive-to, o:deliver-within, t:text는 받아들이지만 아무것도 바꾸지 않습니다.
응답과 오류
- 발송은
Queued. Thank you.메시지와id를 담아 200으로 응답합니다.id는 꺾쇠괄호로 감싼 OpenEmail 메시지 ID이며,GET /emails/{id}와 웹훅은 괄호 없이 씁니다. 배치 발송은 수신자마다 한 통을 만들고 각각 자기 ID를 가지며, 첫 번째 ID로 응답합니다.Idempotency-Key헤더는 API의 다른 곳과 똑같이 동작합니다. - 키가 없거나 알 수 없으면 일반 텍스트
Forbidden과 함께 401을, 워크스페이스에 없는 도메인은Domain not found와 함께 404를 받습니다. 그 밖의 모든 것은message로 돌아옵니다. 보낼 수 없는 메시지는 400,emails:send가 없는 키, 키가 쓸 수 없는 From 주소, 아직 보낼 수 없는 도메인, 발송 한도를 다 쓴 워크스페이스는 403, 25MB를 넘는 본문이나 5MB를 넘는 첨부는 413입니다. - 다른 수신자가 받아들여진 뒤 배치의 한 수신자가 실패하면, 오류가 이미 보낸 메시지를 알려 주고 400으로 응답합니다. 재시도하는 SDK가 같은 메시지를 두 번 보내지 않게 하기 위해서입니다.