sendgo 1.4.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b098fb0eec763f43b7d70391b8a7fa5840960adc8abdf0d75f7a88106741a67
-  data.tar.gz: '078319bc664b5d4cb9cef93db7ba02906e4125379d2a8f0775f9f9d39d9853e7'
+  metadata.gz: 831e137eed970e07e04ea53d57b4c11e84da2dda290e64d5e2645e5550e8c526
+  data.tar.gz: 00f23753365220f337bf5a478f471295393d9453d858d0532c8f070cc5039372
 SHA512:
-  metadata.gz: e90950557127c42fb44fd94c297d8e4cd5995ddc1e34da038d30ed95286985aa976a0f0c93b64364812d3866c8d713622d26b4b8d578e507ba2ace574b1648f1
-  data.tar.gz: a746896ca8b37b6e06507a5800b58372826531cb6ff26233e89111c5304ad3d28e2f1c91c0450542ce411cb602f8984378ad2d3aed8387ded7b4b03edf251f9c
+  metadata.gz: 5b29c3df4cadcc7dcd56a0e9620dc50545cd0e9696e5ebb1c74875226a3bb99ae16282027c624705ac9e84013e1ce656d6d89c2e5b4a6408eb0f01d9e917d5a2
+  data.tar.gz: 14bacdaffd0180a51adb7a08ea56103dbb2bbb5a3137970231aec2994d92df745f4371394ae0b03b769a657ccb6364aa27274efd0f468fefc4e57ba0af35eb7c

data/README.md

@@ -153,7 +153,7 @@ client.friendtalk.send(
 > v2 전용입니다. 자유 본문 타입(`FT`/`FI`/`FW`)을 개별 수신자에게 보낼 때는 여전히 친구톡 API 를 쓰세요 — 이 엔드포인트는 그 조합에 `NOT_A_BRAND_MESSAGE` 를 반환합니다. 친구톡 요청은 카카오 측에서 브랜드메시지(자유형)로 대체 발송됩니다.
 
 ```ruby
-# 단건 발송 — 채널 친구 대상
+# 단건 발송 — 지정 수신자 대상
 client.brand_message.send(
   targeting: "M",
   message_type: "FL",
@@ -674,7 +674,7 @@ MIT License © 2026 [Sendgo](https://sendgo.io)
 
 *키워드: 카카오 알림톡 Ruby, 카카오 친구톡 Rails, SMS 발송 Ruby, 알림톡 Ruby gem, Ruby 카카오 API 연동, Sendgo Ruby SDK, Rails 알림 발송*
 
-## 계정·조직·API 키 관리 (1.4.0)
+## 계정·조직·API 키 관리 (1.6.0)
 
 발송용 `accessKey`/`secretKey`가 없는 단계에서 사용하는 **별도 계정 클라이언트**입니다.
 콘솔에서 발급받은 에이전트 토큰(`SENDGO_AGENT_TOKEN`)으로 `/api/v2/account`를 호출합니다.
@@ -698,3 +698,64 @@ issued = account.create_api_key({ name: '서버 연동' })
 지원 메서드: `me`, `organizations`, `select_organization`, `api_keys`, `create_api_key`, `api_key`, `update_api_key`, `delete_api_key`, `issue_token`, `allowed_ips`, `add_allowed_ip`, `delete_allowed_ip`.
 
 키 생성 인자는 `name`, 선택적 `ipAddresses: [{ip, description}]`이며, 허용 IP 추가 인자는 `ip`, 선택적 `description`입니다. 키·IP 식별자는 응답의 `id`(UUID)를 사용합니다.
+
+## 템플릿 폴더 (1.6.0)
+
+기업 계정의 발송용 API 키와 `apiVersion=v2` 설정으로 사용하는 서버 전용 API입니다.
+폴더는 알림톡·브랜드메시지가 공유하며, 목록의 `templateType`은 `notice` 또는 `brand`입니다.
+목록은 `data.folders` 트리와 `total`, `uncategorised` 개수를 반환합니다.
+`templateCount`는 하위 폴더를 제외한 해당 폴더의 템플릿 수입니다.
+
+- 생성: `name`, 선택 `parentUuid`. 최대 5단계이며 같은 부모 아래 이름 중복은 409입니다.
+- 이동: 동일 발신프로필의 `templateCodes` 1~100개. `folderUuid`는 필수이며 `null`이면 미분류로 이동합니다.
+- 템플릿 목록: `folderUuid=none`은 미분류, UUID는 해당 폴더, 생략은 전체입니다.
+- 템플릿 등록: 선택 필드 `folderUuid`로 폴더를 지정합니다. 기존 템플릿 수정 API 대신 폴더 이동 API를 사용하세요.
+
+승인되지 않은 키의 `403 ACCESS_KEY_NOT_APPROVED`는 토큰 재발급·재시도 없이 반환합니다.
+계정 API의 `autoApprove`는 서버 설정의 실제 승인 정책을 나타냅니다.
+
+```ruby
+client.template_folders.list(template_type: "notice")
+client.template_folders.create(name: "주문 안내")
+client.template_folders.assign(
+  template_type: "notice", kakao_sender_key: kakao_sender_key,
+  template_codes: ["ORDER_001"], folder_uuid: nil
+)
+client.notice_templates.list(folder_uuid: "none")
+# 템플릿 생성 시 folder_uuid: 폴더_UUID를 선택 인자로 전달합니다.
+```
+
+## 1.6 이메일 API와 브랜드 타기팅
+
+이메일은 서버 전용이며 클라이언트 설정에서 API 버전을 `v2`로 지정합니다.
+브랜드 타기팅은 `M`(친구+비친구), `N`(비친구), `I`(친구교집합),
+`O`(친구만), `F`(동보)를 지원합니다. `O`는 SDK에서 바꾸지 않고 서버로 전달합니다.
+
+이메일 발송·견적·조회·취소, 발신자·도메인 인증, 자격증명, 수신함·원본 EML,
+템플릿·주소록·연락처·발신자 프로필·캠페인 API를 지원합니다.
+일반 API는 기존 앱 Bearer 인증을 사용합니다. `EmailService`의
+`withCredentials` / `with_credentials` / `WithCredentials` / Go `NewEmailWithCredentials`는
+별도로 발급된 이메일 credential ID/password를 사용하며 `/api/v2/email-service`로 호출합니다.
+이 인증은 auth, 발송·견적·조회·취소와 도메인 API에만 사용할 수 있습니다.
+내부 email-gateway, 공개 서명 수신거부 URL은 SDK 관리 API가 아닙니다.
+
+단건 `to`는 이메일 주소 하나입니다. `send`에는 `idempotency_key`를 반드시 지정하고
+같은 발송의 재시도에는 같은 키를 재사용하세요. 캠페인 발송에는 견적 응답의
+`quote_hash`와 `idempotency_key`가 필요합니다. SDK가 키를 임의 생성하거나
+네트워크 오류·429·5xx를 자동 재시도하지 않습니다. Bearer 401만 최대 한 번
+갱신하며, 이메일 권한 거부 403 및 Basic 인증 실패는 그대로 반환합니다.
+마케팅 발송에는 `sender_name`, `sender_address`, `sender_contact`도 필요합니다.
+첨부는 `attachments: [{name, type, content}]`이며 content는 base64입니다.
+
+응답은 서버 JSON 객체 또는 배열을 그대로 반환하며 204는 null/nil/None입니다.
+원본 EML은 바이트(PHP/Ruby는 바이트 문자열)로 반환합니다. Java/Go/.NET/Dart는
+여러 응답 형태를 담는 Object/any/object/dynamic을 사용합니다(.NET JSON은 JsonElement).
+모든 관리 요청 본문은 서버 필드명(snake_case)을 그대로 사용합니다.
+
+아래 `client`는 기존 방식으로 구성한 v2 클라이언트입니다.
+
+```ruby
+client.email.send({from: 'sender@example.com', to: 'recipient@example.com',
+  subject: '접수 안내', purpose: 'transactional', text: '접수되었습니다.',
+  idempotency_key: 'order-123-email'})
+```

data/lib/sendgo/brand_message.rb

@@ -8,7 +8,7 @@ module Sendgo
   # 친구톡과 달리 채널 친구가 아닌 수신자에게도 보낼 수 있고(+targeting: "N"+),
   # 수신 동의한 전체 채널 친구에게 동보 발송할 수 있다(+targeting: "F"+).
   #
-  # @example 단건 발송 — 채널 친구 대상
+  # @example 단건 발송 — 지정 수신자 대상
   #   client.brand_message.send(
   #     targeting: "M",
   #     message_type: "FL",
@@ -30,7 +30,7 @@ module Sendgo
 
     # 브랜드메시지를 전송한다.
     #
-    # +targeting+ 이 "M"/"N"/"I" 이면 +contacts+ 가 필요하고 응답 data 에
+    # +targeting+ 이 "M"/"N"/"I"/"O" 이면 +contacts+ 가 필요하고 응답 data 에
     # 발송 건수(sentCount)가 담긴다. "F" 는 동보 발송이라 +contacts+ 없이
     # 접수 여부(accepted)만 반환되므로, 그 경우 #broadcast 가 더 명확하다.
     #

data/lib/sendgo/client.rb

@@ -12,6 +12,7 @@ module Sendgo
   class Client
     # brand_message: 카카오 브랜드메시지 — 친구톡의 후속 채널. v2 전용.
     # friendtalk: @deprecated 2025-12-31 종료. brand_message 를 사용하세요.
+    attr_reader :email
     attr_reader :alimtalk, :friendtalk, :brand_message, :short_url, :sms
 
     # 관리 API (v2 전용) — 콘솔에서만 되던 등록·심사.
@@ -22,7 +23,7 @@ module Sendgo
     # 화면에서 끝난다 — request_token 이 채널 관리자 휴대폰으로 SMS 를 보내고,
     # 사용자가 입력한 코드를 create 가 받는다. 휴대폰 발신번호는 PASS 대신
     # 신분증 사본을 첨부해 접수하면 sendgo 가 대신 심사한다.
-    attr_reader :kakao_senders, :notice_templates, :brand_templates,
+    attr_reader :template_folders, :kakao_senders, :notice_templates, :brand_templates,
                 :sender_registration, :message_templates,
                 :kakao_images, :rejected_numbers, :webhook
 
@@ -34,6 +35,7 @@ module Sendgo
                                        secret_key: secret_key, api_version: api_version)
       http = HttpClient.new(token_manager: token_manager, base_url: base_url, api_version: api_version)
 
+      @email = EmailService.new(token_manager: token_manager, base_url: base_url, api_version: api_version)
       @alimtalk   = AlimtalkService.new(http: http, kakao_sender_key: kakao_sender_key, sms_sender_key: sms_sender_key)
       @friendtalk = FriendtalkService.new(http: http, kakao_sender_key: kakao_sender_key, sms_sender_key: sms_sender_key)
       @brand_message = BrandMessageService.new(http: http, kakao_sender_key: kakao_sender_key, sms_sender_key: sms_sender_key)
@@ -42,6 +44,7 @@ module Sendgo
       @sms        = SmsService.new(http: http, sms_sender_key: sms_sender_key)
 
       @kakao_senders       = KakaoSenderService.new(http: http)
+      @template_folders    = TemplateFolderService.new(http: http)
       @notice_templates    = NoticeTemplateService.new(http: http)
       @brand_templates     = BrandTemplateService.new(http: http)
       @sender_registration = SenderRegistrationService.new(http: http)

data/lib/sendgo/email.rb

@@ -0,0 +1,246 @@
+require "net/http"
+require "json"
+require "base64"
+require "uri"
+module Sendgo
+  # 서버 전용 이메일 API. 객체·배열·204(nil)·EML(String)을 보존합니다.
+  class EmailService
+    def initialize(token_manager: nil, base_url: "https://sendgo.io", api_version: "v2", credential: nil)
+      @tokens, @base_url, @api_version, @credential = token_manager, base_url.sub(%r{/$}, ""), api_version, credential
+    end
+    # 앱 키가 아닌 이메일 전용 credential ID/password입니다.
+    def self.with_credentials(id, password, base_url: "https://sendgo.io")
+      new(base_url: base_url, credential: Base64.strict_encode64("#{id}:#{password}"))
+    end
+
+    private
+    def encode(value)
+      URI.encode_www_form_component(value.to_s).gsub("+", "%20")
+    end
+    def request(method, path, body = nil, query = {}, raw = false, retrying = false)
+      raise ArgumentError, "이메일 API는 api_version=v2가 필요합니다." unless @api_version == "v2"
+      basic = !@credential.nil?
+      prefix = basic ? "email-service" : "email"
+      uri = URI("#{@base_url}/api/v2/#{prefix}/#{path}")
+      uri.query = URI.encode_www_form(query.reject { |_,v| v.nil? }) unless query.empty?
+      req = Net::HTTPGenericRequest.new(method, !body.nil?, true, uri.request_uri)
+      req["Authorization"] = basic ? "Basic #{@credential}" : "Bearer #{@tokens.get_token}"
+      req["Accept"] = "application/json"
+      unless body.nil?
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(body)
+      end
+      resp = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: 60, open_timeout: 10) { |h| h.request(req) }
+      ok = resp.is_a?(Net::HTTPSuccess)
+      return resp.body.to_s.b if ok && raw
+      begin
+        data = resp.body.nil? || resp.body.empty? ? nil : JSON.parse(resp.body)
+      rescue JSON::ParserError
+        raise if ok
+        data = {}
+      end
+      unless ok
+        error = data.is_a?(Hash) ? data : {}
+        if !retrying && !basic && resp.code.to_i == 401 && @tokens.should_refresh?(401, error["code"])
+          @tokens.invalidate
+          return request(method, path, body, query, raw, true)
+        end
+        raise SendgoError.from_response(resp.code.to_i, error, path, "v2")
+      end
+      data
+    end
+    public
+    # GET /email/account
+    def account(query = {})
+      request("GET", "account", nil, query, false)
+    end
+    # POST /email/request
+    def request_access(body = {})
+      request("POST", "request", body, {}, false)
+    end
+    # POST /email/credentials
+    def create_credential(body = {})
+      request("POST", "credentials", body, {}, false)
+    end
+    # GET /email/credentials
+    def credentials(query = {})
+      request("GET", "credentials", nil, query, false)
+    end
+    # DELETE /email/credentials/{id}
+    def revoke_credential(id)
+      request("DELETE", "credentials/#{encode(id)}", nil, {}, false)
+    end
+    # GET /email/domains
+    def domains(query = {})
+      request("GET", "domains", nil, query, false)
+    end
+    # POST /email/domains
+    def register_domain(body = {})
+      request("POST", "domains", body, {}, false)
+    end
+    # POST /email/domains/{id}/verify
+    def verify_domain(id, body = {})
+      request("POST", "domains/#{encode(id)}/verify", body, {}, false)
+    end
+    # GET /email/senders
+    def senders(query = {})
+      request("GET", "senders", nil, query, false)
+    end
+    # POST /email/senders
+    def request_sender(body = {})
+      request("POST", "senders", body, {}, false)
+    end
+    # POST /email/senders/{id}/verify
+    def verify_sender(id, body = {})
+      request("POST", "senders/#{encode(id)}/verify", body, {}, false)
+    end
+    # POST /email/recipients/verification
+    def request_recipient_verification(body = {})
+      request("POST", "recipients/verification", body, {}, false)
+    end
+    # POST /email/recipients/check
+    def check_recipients(body = {})
+      request("POST", "recipients/check", body, {}, false)
+    end
+    # GET /email/address-book
+    def address_book(query = {})
+      request("GET", "address-book", nil, query, false)
+    end
+    # GET /email/sender-profiles
+    def sender_profiles(query = {})
+      request("GET", "sender-profiles", nil, query, false)
+    end
+    # POST /email/sender-profiles
+    def create_sender_profile(body = {})
+      request("POST", "sender-profiles", body, {}, false)
+    end
+    # PATCH /email/sender-profiles/{id}
+    def update_sender_profile(id, body = {})
+      request("PATCH", "sender-profiles/#{encode(id)}", body, {}, false)
+    end
+    # DELETE /email/sender-profiles/{id}
+    def delete_sender_profile(id)
+      request("DELETE", "sender-profiles/#{encode(id)}", nil, {}, false)
+    end
+    # POST /email/address-book/import
+    def import_address_book(body = {})
+      request("POST", "address-book/import", body, {}, false)
+    end
+    # POST /email/address-book/preferences
+    def update_address_book_preferences(body = {})
+      request("POST", "address-book/preferences", body, {}, false)
+    end
+    # POST /email/send
+    def send(body)
+      request("POST", "send", body, {}, false)
+    end
+    # POST /email/quote
+    def quote(body = {})
+      request("POST", "quote", body, {}, false)
+    end
+    # GET /email/messages
+    def messages(query = {})
+      request("GET", "messages", nil, query, false)
+    end
+    # GET /email/messages/{id}
+    def message(id, query = {})
+      request("GET", "messages/#{encode(id)}", nil, query, false)
+    end
+    # POST /email/messages/{id}/cancel
+    def cancel_message(id, body = {})
+      request("POST", "messages/#{encode(id)}/cancel", body, {}, false)
+    end
+    # GET /email/inboxes
+    def inboxes(query = {})
+      request("GET", "inboxes", nil, query, false)
+    end
+    # POST /email/inboxes
+    def create_inbox(body = {})
+      request("POST", "inboxes", body, {}, false)
+    end
+    # PATCH /email/inboxes/{id}
+    def update_inbox(id, body = {})
+      request("PATCH", "inboxes/#{encode(id)}", body, {}, false)
+    end
+    # GET /email/inboxes/{id}/messages
+    def inbox_messages(id, query = {})
+      request("GET", "inboxes/#{encode(id)}/messages", nil, query, false)
+    end
+    # GET /email/inboxes/{id}/messages/{messageId}
+    def inbox_message(id, message_id, query = {})
+      request("GET", "inboxes/#{encode(id)}/messages/#{encode(message_id)}", nil, query, false)
+    end
+    # GET /email/inboxes/{id}/messages/{messageId}/raw
+    def raw_message(id, message_id, query = {})
+      request("GET", "inboxes/#{encode(id)}/messages/#{encode(message_id)}/raw", nil, query, true)
+    end
+    # DELETE /email/inboxes/{id}/messages/{messageId}
+    def delete_inbox_message(id, message_id)
+      request("DELETE", "inboxes/#{encode(id)}/messages/#{encode(message_id)}", nil, {}, false)
+    end
+    # GET /email/templates
+    def templates(query = {})
+      request("GET", "templates", nil, query, false)
+    end
+    # GET /email/templates/{id}
+    def template(id, query = {})
+      request("GET", "templates/#{encode(id)}", nil, query, false)
+    end
+    # POST /email/templates
+    def create_template(body = {})
+      request("POST", "templates", body, {}, false)
+    end
+    # PATCH /email/templates/{id}
+    def update_template(id, body = {})
+      request("PATCH", "templates/#{encode(id)}", body, {}, false)
+    end
+    # DELETE /email/templates/{id}
+    def delete_template(id)
+      request("DELETE", "templates/#{encode(id)}", nil, {}, false)
+    end
+    # GET /email/contacts
+    def contacts(query = {})
+      request("GET", "contacts", nil, query, false)
+    end
+    # POST /email/contacts
+    def save_contact(body = {})
+      request("POST", "contacts", body, {}, false)
+    end
+    # POST /email/contacts/import
+    def import_contacts(body = {})
+      request("POST", "contacts/import", body, {}, false)
+    end
+    # POST /email/contacts/{id}/unsubscribe
+    def unsubscribe_contact(id, body = {})
+      request("POST", "contacts/#{encode(id)}/unsubscribe", body, {}, false)
+    end
+    # GET /email/campaigns
+    def campaigns(query = {})
+      request("GET", "campaigns", nil, query, false)
+    end
+    # POST /email/campaigns
+    def create_campaign(body = {})
+      request("POST", "campaigns", body, {}, false)
+    end
+    # GET /email/campaigns/{id}
+    def campaign(id, query = {})
+      request("GET", "campaigns/#{encode(id)}", nil, query, false)
+    end
+    # POST /email/campaigns/{id}/quote
+    def quote_campaign(id, body = {})
+      request("POST", "campaigns/#{encode(id)}/quote", body, {}, false)
+    end
+    # POST /email/campaigns/{id}/send
+    def send_campaign(id, body = {})
+      request("POST", "campaigns/#{encode(id)}/send", body, {}, false)
+    end
+    # POST /email/campaigns/{id}/cancel
+    def cancel_campaign(id, body = {})
+      request("POST", "campaigns/#{encode(id)}/cancel", body, {}, false)
+    end
+    # GET /email/auth
+    def auth(query = {})
+      request("GET", "auth", nil, query, false)
+    end
+  end
+end

data/lib/sendgo/management.rb

@@ -119,9 +119,10 @@ module Sendgo
     end
 
     # 목록 조회.
-    def list(kakao_sender_key: nil, inspection_status: nil, search: nil, count: nil)
+    def list(kakao_sender_key: nil, inspection_status: nil, search: nil, count: nil, folder_uuid: nil)
       @http.get(RESOURCE, {
                   kakaoSenderKey: kakao_sender_key,
+                  folderUuid: folder_uuid,
                   inspectionStatus: inspection_status,
                   search: search,
                   count: count
@@ -250,8 +251,8 @@ module Sendgo
     end
 
     # 목록 조회.
-    def list(kakao_sender_key: nil, search: nil, count: nil)
-      @http.get(RESOURCE, { kakaoSenderKey: kakao_sender_key, search: search, count: count })
+    def list(kakao_sender_key: nil, search: nil, count: nil, folder_uuid: nil)
+      @http.get(RESOURCE, { folderUuid: folder_uuid, kakaoSenderKey: kakao_sender_key, search: search, count: count })
     end
 
     # 상세 조회. sendgo 코드(+KFT-...+)와 카카오 브랜드 템플릿 코드 둘 다 받는다.
@@ -594,3 +595,28 @@ module Sendgo
     end
   end
 end
+
+module Sendgo
+  # 템플릿 공용 폴더. v2 전용, 기업 계정 전용.
+  class TemplateFolderService
+    def initialize(http:)
+      @http = http
+    end
+
+    def list(template_type: nil, kakao_sender_key: nil)
+      @http.get("template-folders", { templateType: template_type, kakaoSenderKey: kakao_sender_key })
+    end
+
+    def create(name:, parent_uuid: nil)
+      @http.post("template-folders", { name: name, parentUuid: parent_uuid })
+    end
+
+    # folder_uuid: nil이면 미분류로 이동합니다. 1~100개 코드가 필요합니다.
+    def assign(template_type:, kakao_sender_key:, template_codes:, folder_uuid:)
+      @http.patch("template-folders/templates", {
+        templateType: template_type, kakaoSenderKey: kakao_sender_key,
+        templateCodes: template_codes, folderUuid: folder_uuid
+      })
+    end
+  end
+end

data/lib/sendgo/version.rb

@@ -1,3 +1,3 @@
 module Sendgo
-  VERSION = "1.4.0"
+  VERSION = "1.6.0"
 end

data/lib/sendgo.rb

@@ -8,6 +8,7 @@ require_relative "sendgo/brand_message"
 require_relative "sendgo/short_url"
 require_relative "sendgo/sms"
 require_relative "sendgo/management"
+require_relative "sendgo/email"
 require_relative "sendgo/client"
 
 # Sendgo Ruby SDK — 카카오 알림톡/친구톡, SMS/LMS/MMS

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sendgo
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Sendgo
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-22 00:00:00.000000000 Z
+date: 2026-10-03 00:00:00.000000000 Z
 dependencies: []
 description: Sendgo API를 Ruby에서 간편하게 사용하기 위한 공식 SDK
 email:
@@ -23,6 +23,7 @@ files:
 - lib/sendgo/alimtalk.rb
 - lib/sendgo/brand_message.rb
 - lib/sendgo/client.rb
+- lib/sendgo/email.rb
 - lib/sendgo/error.rb
 - lib/sendgo/friendtalk.rb
 - lib/sendgo/http_client.rb