{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/email-api/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Mailjet Ruby SDK","siteUrl":"https://dev.mailjet.com/","projectTitle":"Mailjet Developer Documentation","description":"Install and use the official Mailjet Ruby gem: authentication, sending with Send API v3.1, REST requests, ActionMailer delivery and event tracking.","image":"https://dev.mailjet.com/og-image.png","lang":"en-US","keywords":["Mailjet API","Email API","Content API","SMTP Relay","transactional email","email delivery","Send API","email templates","developer documentation"],"meta":[{"name":"og:type","content":"website"},{"name":"og:site_name","content":"Mailjet Developer Documentation"},{"name":"twitter:card","content":"summary_large_image"},{"name":"robots","content":"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1"},{"name":"googlebot","content":"index, follow, max-snippet:-1, max-image-preview:large"}],"jsonLd":{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://dev.mailjet.com/#organization","name":"Mailjet","alternateName":"Sinch Mailjet","url":"https://www.mailjet.com","logo":"https://assets.mailjet.com/lib/images/mailjetLogo/mj_logo_with_text_color.png","parentOrganization":{"@type":"Organization","name":"Sinch","url":"https://www.sinch.com"}},{"@type":"WebSite","@id":"https://dev.mailjet.com/#website","name":"Mailjet Developer Documentation","description":"Official developer documentation for the Mailjet Email API, Content API and SMTP Relay.","url":"https://dev.mailjet.com/","inLanguage":"en-US","publisher":{"@id":"https://dev.mailjet.com/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://dev.mailjet.com/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]},"llmstxt":{"hide":false,"title":"Mailjet Developer Documentation","description":"Developer documentation for the Mailjet Email API, Content API and SMTP Relay - guides, API references and code samples for sending, templating and tracking email at scale.","details":{"content":"Mailjet (part of Sinch) provides APIs for sending and managing email.\n\nThis documentation covers four main areas:\n\n- **Email API** - the Send API (v3 and v3.1) for transactional and marketing email,\n  plus contact management, segmentation, campaigns, statistics, webhooks, the Parse API\n  and the Mailjet Templating Language.\n- **Content API** - programmatic management of email templates, template contents,\n  images, labels and authentication tokens (v1).\n- **SMTP Relay** - sending through Mailjet's SMTP servers, including custom headers.\n- **API Reference** - the complete, generated reference for every endpoint, built directly\n  from the OpenAPI specifications.\n\nBase URL for all REST APIs: `https://api.mailjet.com`.\nAuthentication uses HTTP Basic auth with an API key and secret key.\n\n## Machine-readable entry points\n\nPrefer these when you need the API surface in as few requests as possible:\n\n- `/openapi/openapi-mailjet.md` - the **complete** Email API reference (every endpoint,\n  grouped by resource) as a single Markdown document.\n- `/openapi/openapi-passport.md` - the **complete** Content API reference as a single\n  Markdown document.\n- `/_bundle/openapi/openapi-mailjet.yaml` - the raw, fully bundled OpenAPI 3 description\n  of the Email API.\n- `/_bundle/openapi/openapi-passport.yaml` - the raw, fully bundled OpenAPI 3 description\n  of the Content API.\n- `/sitemap.xml` - every indexable URL on this site.\n\nEvery page on this site is also available as clean Markdown by appending `.md` to its URL."},"sections":[{"title":"Email API","description":"Sending, contacts, campaigns, statistics, webhooks and templating.","includeFiles":["docs/email-api/**/*.md"],"excludeFiles":[]},{"title":"Content API","description":"Manage templates, template contents, images, labels and tokens.","includeFiles":["docs/content-api/**/*.md","docs/content-api.md"],"excludeFiles":[]},{"title":"SMTP Relay","description":"Send email through Mailjet's SMTP servers.","includeFiles":["docs/smtp-relay/**/*.md"],"excludeFiles":[]},{"title":"API Reference","description":"Complete generated reference for every Mailjet API endpoint.","includeFiles":["openapi/openapi-mailjet.yaml","openapi/openapi-passport.yaml","docs/api-reference/**/*.md"],"excludeFiles":[]},{"title":"Migrating from Mandrill","description":"Guides for switching from Mandrill to Mailjet.","includeFiles":["docs/mandrill/**/*.md"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"ruby-sdk","__idx":0},"children":["Ruby SDK"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The official Ruby wrapper for the Mailjet API is published as the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mailjet"]}]}," gem and developed at ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/mailjet/mailjet-gem"},"children":["mailjet/mailjet-gem"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"compatibility","__idx":1},"children":["Compatibility"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ruby ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["2.2.x"]}," or higher"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ActionMailer integration targets ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rails >= 5"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"installation","__idx":2},"children":["Installation"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"rubygems","__idx":3},"children":["RubyGems"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"gem install mailjet\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"bundler","__idx":4},"children":["Bundler"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"# Gemfile\ngem 'mailjet'\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To track the latest commit on GitHub instead of a released version:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"# Gemfile\ngem 'mailjet', :git => 'https://github.com/mailjet/mailjet-gem.git'\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Then:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"bundle install\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authentication","__idx":5},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configure the gem in an initializer:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"# config/initializers/mailjet.rb\nMailjet.configure do |config|\n  config.api_key = ENV['MJ_APIKEY_PUBLIC']\n  config.secret_key = ENV['MJ_APIKEY_PRIVATE']\n  config.default_from = 'my_registered_sender@example.com'\nend\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On Rails you can generate the initializer:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"rails generate mailjet:initializer\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["default_from"]}," is optional when you send through ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#send-emails-with-actionmailer"},"children":["Mailjet's SMTP relay with ActionMailer"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"send-your-first-email","__idx":6},"children":["Send your first email"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"require 'mailjet'\n\nMailjet.configure do |config|\n  config.api_key = ENV['MJ_APIKEY_PUBLIC']\n  config.secret_key = ENV['MJ_APIKEY_PRIVATE']\n  config.api_version = 'v3.1'\nend\n\nresponse = Mailjet::Send.create(messages: [{\n  'From' => {\n    'Email' => 'pilot@example.com',\n    'Name' => 'Mailjet Pilot'\n  },\n  'To' => [\n    {\n      'Email' => 'passenger@example.com',\n      'Name' => 'Passenger 1'\n    }\n  ],\n  'Subject' => 'My first Mailjet Email!',\n  'TextPart' => 'Greetings from Mailjet!',\n  'HTMLPart' => '<h3>Dear passenger 1, welcome to Mailjet!</h3>'\n}])\n\np response.attributes[:messages]\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"call-configuration","__idx":7},"children":["Call configuration"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"api-versioning","__idx":8},"children":["API versioning"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Version"},"children":["Version"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Scope"},"children":["Scope"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v3"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Email API"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v3.1"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Send API v3.1 (latest send version)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v4"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["SMS API — ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not yet supported by this library"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Most Email API endpoints sit under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v3"]},", which is the default. For anything else, set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api_version"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"Mailjet.configure do |config|\n  config.api_key = ENV['MJ_APIKEY_PUBLIC']\n  config.secret_key = ENV['MJ_APIKEY_PRIVATE']\n  config.api_version = 'v3.1'\nend\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"base-url","__idx":9},"children":["Base URL"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The default base domain is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.mailjet.com"]},". Override it with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end_point"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"Mailjet.configure do |config|\n  config.api_key = ENV['MJ_APIKEY_PUBLIC']\n  config.secret_key = ENV['MJ_APIKEY_PRIVATE']\n  config.api_version = 'v3.1'\n  config.end_point = 'https://api.us.mailjet.com'\nend\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Accounts on Mailjet's ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["US architecture"]}," must set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.us.mailjet.com"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"naming-conventions","__idx":10},"children":["Naming conventions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The gem follows Ruby conventions rather than the API's casing:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Class names"]}," capitalise only the first letter of the resource name — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["listrecipient"]}," becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Mailjet::Listrecipient"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Attribute names"]}," are the underscored form of the API property — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IsActive"]}," becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_active"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Action endpoints"]}," join resource and action with an underscore — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/contact/{id}/managecontactslists"]}," becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Mailjet::Contact_managecontactslists"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The full resource list is in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/mailjet/mailjet-gem/tree/master/lib/mailjet/resources"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/lib/mailjet/resources"]}]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"request-examples","__idx":11},"children":["Request examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"post--create-an-object","__idx":12},"children":["POST — create an object"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"contact = Mailjet::Contact.create(email: 'passenger@example.com')\np contact.attributes['Data']\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"post--endpoints-with-an-action","__idx":13},"children":["POST — endpoints with an action"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," to identify the object the action applies to:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"result = Mailjet::Contact_managecontactslists.create(id: contact_id, contacts_lists: [\n  {\n    'ListID' => list_id_1,\n    'Action' => 'addnoforce'\n  },\n  {\n    'ListID' => list_id_2,\n    'Action' => 'addforce'\n  }\n])\n\np result.attributes['Data']\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"get--all-objects","__idx":14},"children":["GET — all objects"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".all"]}," returns 10 objects by default. Pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit: 0"]}," to retrieve everything, up to 1000 objects."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"recipients = Mailjet::Listrecipient.all(limit: 0)\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"get--with-filters","__idx":15},"children":["GET — with filters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Queries accept API filters plus these parameters:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Values"},"children":["Values"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Default"},"children":["Default"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["format"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":json"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":xml"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":rawxml"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":html"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":csv"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":phpserialized"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":json"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["10"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["offset"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sort"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[[:property, :asc], [:property, :desc]]"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"# all contacts in contact list 123\ncontacts = Mailjet::Contact.all(limit: 0, contacts_list: 123)\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"get--a-single-object","__idx":16},"children":["GET — a single object"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"contact = Mailjet::Contact.find('passenger@example.com')\np contact.attributes['Data']\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two convenience helpers are also available:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"Mailjet::Contact.count\n# => 83\n\nMailjet::Contact.first\n# => #<Mailjet::Contact>\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"put--update-an-object","__idx":17},"children":["PUT — update an object"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT"]}," in the Mailjet API behaves like a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH"]},": only the properties you send are updated, and non-mandatory properties can be omitted."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"recipient = Mailjet::Listrecipient.first\nrecipient.is_active = false\nrecipient.save\n\n# or in one call\nrecipient.update_attributes(is_active: true)\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"delete--remove-an-object","__idx":18},"children":["DELETE — remove an object"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]}," returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204 No Content"]}," with no response body."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"recipient = Mailjet::Listrecipient.first\nrecipient.delete\n\n# or by ID\nMailjet::Listrecipient.delete(123)\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"contact-management","__idx":19},"children":["Contact management"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"import-contacts-from-csv","__idx":20},"children":["Import contacts from CSV"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Build the CSV in the format described in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://dev.mailjet.com/email/guides/contact-management/#manage-contacts-via-csv-upload"},"children":["Manage contacts via CSV upload"]},", then:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"Mailjet::ContactslistCsv.send_data(contact_list_id, File.open('contacts.csv', 'r'))\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"delete-a-contact-gdpr","__idx":21},"children":["Delete a contact (GDPR)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"Mailjet::ContactPii.delete(contact_id)\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"send-emails-with-actionmailer","__idx":22},"children":["Send emails with ActionMailer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set the delivery method to Mailjet's SMTP relay:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"# application.rb, or a config/environments file\nconfig.action_mailer.delivery_method = :mailjet\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Or send through the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://dev.mailjet.com/email/guides/send-api-v31/"},"children":["Send API"]}," instead:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"# application.rb\nconfig.action_mailer.delivery_method = :mailjet_api\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"per-message-options","__idx":23},"children":["Per-message options"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Mailjet-specific options are passed through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delivery_method_options"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"class AwesomeMailer < ApplicationMailer\n  def awesome_mail(user)\n    mail(\n      to: user.email,\n      delivery_method_options: { api_key: 'your-api-key', secret_key: 'your-secret-key' }\n    )\n  end\nend\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To use the latest Send API version, set it explicitly:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"delivery_method_options: { version: 'v3.1' }\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Supported options:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"# v3.1\n:api_key, :secret_key, :'Priority', :'CustomCampaign', :'DeduplicateCampaign',\n:'TemplateLanguage', :'TemplateErrorReporting', :'TemplateErrorDeliver',\n:'TemplateID', :'TrackOpens', :'TrackClicks', :'CustomID', :'EventPayload',\n:'Variables', :'Headers'\n\n# v3\n:recipients, :'mj-prio', :'mj-campaign', :'mj-deduplicatecampaign',\n:'mj-templatelanguage', :'mj-templateerrorreporting', :'mj-templateerrordeliver',\n:'mj-templateid', :'mj-trackopen', :'mj-trackclick', :'mj-customid',\n:'mj-eventpayload', :vars, :headers\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Alternatively, set the Mailjet SMTP headers directly:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"headers['X-MJ-CustomID'] = 'order-1001'\nheaders['X-MJ-EventPayload'] = 'custom payload'\nheaders['X-MJ-TemplateLanguage'] = 'true'\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"a-minimal-mailer","__idx":24},"children":["A minimal mailer"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"rails generate mailer UserMailer\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"# app/mailers/user_mailer.rb\nclass UserMailer < ApplicationMailer\n  def welcome_email\n    headers['X-MJ-CustomID'] = 'welcome-email'\n\n    mail(\n      from: 'pilot@example.com',\n      to: 'passenger@example.com',\n      subject: 'This is a nice welcome email'\n    )\n  end\nend\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"erb","header":{"controls":{"copy":{}}},"source":"<%# app/views/user_mailer/welcome_email.html.erb %>\nHello world in HTML!\n","lang":"erb"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"erb","header":{"controls":{"copy":{}}},"source":"<%# app/views/user_mailer/welcome_email.text.erb %>\nHello world in plain text!\n","lang":"erb"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"UserMailer.welcome_email.deliver_now!\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the Rails guides on ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://guides.rubyonrails.org/action_mailer_basics.html"},"children":["ActionMailer"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://api.rubyonrails.org/classes/ActionMailer/MessageDelivery.html"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ActionMailer::MessageDelivery"]}]}," for the rest."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"track-email-delivery","__idx":25},"children":["Track email delivery"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The gem ships a Rack endpoint that receives Mailjet event callbacks (opens, clicks, bounces and so on)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["First register your endpoint URL under ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://app.mailjet.com/account/triggers"},"children":["account triggers"]},", then mount the middleware on the same path:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"# application.rb\nconfig.middleware.use Mailjet::Rack::Endpoint, '/mailjet/callback' do |params|\n  # original_address is set for typofix events\n  email = params['email'].presence || params['original_address']\n\n  if user = User.find_by_email(email)\n    user.process_email_callback(params)\n  else\n    Rails.logger.fatal \"[Mailjet] User not found: #{email} -- DUMP #{params.inspect}\"\n  end\nend\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"# app/models/user.rb\nclass User < ActiveRecord::Base\n  def process_email_callback(params)\n    case params['event']\n    when 'open'\n      # the tracking pixel was loaded — the recipient allowed images\n    when 'click'\n      # a tracked link was clicked\n    when 'bounce'\n      # recipient not found — is the address valid?\n    when 'spam'\n      # the gateway or the recipient flagged the message\n    when 'blocked'\n      # the gateway or the recipient blocked the sender\n    when 'typofix'\n      # rerouted from params['original_address'] to params['new_address']\n    else\n      Rails.logger.fatal \"[Mailjet] Unknown event #{params['event']} -- DUMP #{params.inspect}\"\n    end\n  end\nend\n","lang":"ruby"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Because this is a Rack application, any Rack-compatible framework works — Sinatra, Padrino and others."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"testing","__idx":26},"children":["Testing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Parts of the gem's test suite run against Mailjet's live servers, so valid credentials are required. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Do not use a production account"]}," — some tests are destructive."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# GEM_ROOT/config.yml\nmailjet:\n  api_key: YOUR_API_KEY\n  secret_key: YOUR_SECRET_KEY\n  default_from: YOUR_REGISTERED_SENDER_EMAIL\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"bundle\nbundle exec rake\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"contribute","__idx":27},"children":["Contribute"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The wrapper is open source. Fork the repository, branch, implement your fix or feature, add documentation and specs, and open a pull request at ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/mailjet/mailjet-gem"},"children":["mailjet/mailjet-gem"]}," — without changes to the gemspec or the version file. Documentation improvements belong in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/mailjet/api-documentation"},"children":["API documentation repo"]},"."]}]},"headings":[{"value":"Ruby SDK","id":"ruby-sdk","depth":1},{"value":"Compatibility","id":"compatibility","depth":2},{"value":"Installation","id":"installation","depth":2},{"value":"RubyGems","id":"rubygems","depth":3},{"value":"Bundler","id":"bundler","depth":3},{"value":"Authentication","id":"authentication","depth":2},{"value":"Send your first email","id":"send-your-first-email","depth":2},{"value":"Call configuration","id":"call-configuration","depth":2},{"value":"API versioning","id":"api-versioning","depth":3},{"value":"Base URL","id":"base-url","depth":3},{"value":"Naming conventions","id":"naming-conventions","depth":2},{"value":"Request examples","id":"request-examples","depth":2},{"value":"POST — create an object","id":"post--create-an-object","depth":3},{"value":"POST — endpoints with an action","id":"post--endpoints-with-an-action","depth":3},{"value":"GET — all objects","id":"get--all-objects","depth":3},{"value":"GET — with filters","id":"get--with-filters","depth":3},{"value":"GET — a single object","id":"get--a-single-object","depth":3},{"value":"PUT — update an object","id":"put--update-an-object","depth":3},{"value":"DELETE — remove an object","id":"delete--remove-an-object","depth":3},{"value":"Contact management","id":"contact-management","depth":2},{"value":"Import contacts from CSV","id":"import-contacts-from-csv","depth":3},{"value":"Delete a contact (GDPR)","id":"delete-a-contact-gdpr","depth":3},{"value":"Send emails with ActionMailer","id":"send-emails-with-actionmailer","depth":2},{"value":"Per-message options","id":"per-message-options","depth":3},{"value":"A minimal mailer","id":"a-minimal-mailer","depth":3},{"value":"Track email delivery","id":"track-email-delivery","depth":2},{"value":"Testing","id":"testing","depth":2},{"value":"Contribute","id":"contribute","depth":2}],"frontmatter":{"title":"Mailjet Ruby SDK","seo":{"title":"Mailjet Ruby SDK","description":"Install and use the official Mailjet Ruby gem: authentication, sending with Send API v3.1, REST requests, ActionMailer delivery and event tracking."}},"lastModified":"2026-08-26T16:26:02.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/email-api/developer-tools/ruby","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}